Copyright © ${copyright.year} ${project.organization.name}. All rights reserved.

Online version published by ${project.organization.name}, ${organization.address}.

Nexus™, Nexus Professional™, and all Nexus-related logos are trademarks or registered trademarks of Sonatype, Inc., in the United States and other countries.

Java™ and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc., in the United States and other countries.

IBM® and WebSphere® are trademarks or registered trademarks of International Business Machines, Inc., in the United States and other countries.

Eclipse™ is a trademark of the Eclipse Foundation, Inc., in the United States and other countries.

Apache and the Apache feather logo are trademarks of The Apache Software Foundation.

Linux® is the registered trademark of Linus Torvalds in the U.S. and other countries.

Many of the designations used by manufacturers and sellers to distinguish their products are claimed as trademarks. Where those designations appear in this book, and ${project.organization.name} was aware of a trademark claim, the designations have been printed in caps or initial caps.

While every precaution has been taken in the preparation of this book, the publisher and authors assume no responsibility for errors or omissions, or for damages resulting from the use of the information contained herein.

Foreword: ${project.version}

This book covers both Nexus Open Source and Nexus Professional, a product which brings full control and visibility to organizations which depend on Maven repositories to manage releases and distribute software. You are encouraged to check http://books.sonatype.com/nexus-book weekly for any updates to the content.

If you would like to receive updates whenever there is a change to this book, you can subscribe to our Book Announcement mailing list. To subscribe to this mailing list, send an email to: book-notify-subscribe@sonatype.org

We welcome your feedback, please do not hesitate to contact the Sonatype team with any questions or ideas you may have about the product. We’re focused on making the adoption of Nexus Open Source and Nexus Professional painless, and we are here to do anything we can to help speed up the learning curve associated with some of the more advanced and powerful features of Nexus.

If you have any feedback or questions, you are encouraged to post an item in our Get Satisfaction page for this book: http://www.getsatisfaction.com/sonatype/products/sonatype_repository_management_with_nexus

Tim O’Brien, Sonatype

${release.month}, ${copyright.year}

Edition: ${project.version}

Changes in Edition 3.0.1

The following changes were made in 3.0.1:

  • Added New Section <xref linkend="using-dependencies" />. (NXBOOK-577)

  • Added a step about setting to LANG to the post-install checklist. (NXBOOK-561)

  • Updated template for new Sonatype web site.

Changes in Edition 3.0

The following changes were made in 3.0:

  • Added Anders Hammar as an author. (NXBOOK-577)

  • Upgrade Nexus version number fo 1.9.0.2. (NXBOOK-580)

  • Removed a section that was focused on providing upgrade instructions for users upgrading from Nexus 1.5 to Nexus 1.6. (NXBOOK-578)

  • Transitioned image generation tools from Photoshop-based Macros to a series of scripts using Imagemagick to scale and create book images. (NXBOOK-579 and NXBOOK-581)

  • Updated Sonatype’s address to Maryland address. (NXBOOK-565)

  • Fixed a minor typo in <xref linkend="installation-sect-upgrading" />. (NXBOOK-499)

  • Removed instructions for upgrading Nexus 1.2 to Nexus 1.3 from <xref linkend="installation-sect-upgrading" />. (NXBOOK-583)

The following people helped improve the quality of Edition 3.0 by reporting typos, making suggestions, or contributing directly to the development of this book:

  • Trevor Harmon for reporting typos in NXBOOK-499.

Introducing Sonatype Nexus

Introduction

Nexus manages software “artifacts” required for development, deployment, and provisioning. If you develop software, Nexus can help you share those artifacts with other developers and end-users. Maven’s central repository has always served as a great convenience for users of Maven, but it has always been recommended to maintain your own repositories to ensure stability within your organization. Nexus greatly simplifies the maintenance of your own internal repositories and access to external repositories. With Nexus you can completely control access to, and deployment of, every artifact in your organization from a single location.

Nexus Open Source

Nexus Open Source provides you with an essential level of control over the external Maven repositories you use and the internal repositories you create. It provides infrastructure and services for organizations that use repository managers to obtain and deliver software. If you create software libraries or applications for your end-users, you can use Nexus Open Source to distribute your software. If your software depends upon open source software components, you can cache software artifacts from remote repositories.

Nexus Open Source Features

Hosting Repositories

When you host a Maven repository with Nexus Open Source, you can upload artifacts using the Nexus interface, or you can deploy artifacts to hosted repositories using Maven. Nexus will also create the standard Nexus Index for all of your hosted repositories which will allow tools like m2eclipse to rapidly locate software artifacts for your developers.

Proxy Remote Repositories

When you proxy a remote repository with Nexus Open source you can control all aspects of the connection to a remote repository including security parameters, HTTP proxy settings. You can configure which mirrors Nexus will download artifacts from, and you can control how long Nexus will store artifacts and how it will expire artifacts which are no longer referenced by your build.

Repository Groups

Grouping repositories allows you to consolidate multiple repositories into a single URL. This makes configuring your development environment very easy. All of your developers can point to a single repository group URL, and if anyone ever needs a custom remote repository added to the group, you can do this in a central location without having to modify every developer’s workstation.

Fine-grained Security Model

Nexus Open Source ships with a very capable and customizable security model. Every operation in Nexus is associated with a privilege, and privileges can be combined into standard Nexus roles. Users can then be assigned both individual privileges and roles that can be applied globally or at a fine grained level. You can create custom administrative roles that limit certain repository actions such as deployment to specific groups of developers and you can use these security roles to model the structure of your organization.

Flexible LDAP Integration

If your organization uses an LDAP server, Nexus Professional can integrate with an external authentication and access control system. Nexus Professional is smart enough to be able to automatically map LDAP groups to the appropriate Nexus roles, and it also provides a very flexible facility for mapping existing users and existing roles to Nexus roles.

Artifact Search

Nexus Open Source provides an intuitive search feature which allows you to search for software artifacts by identifiers such as groupId, artifactId, version, classifier, and packaging, names of classes contained in Java archives, keywords, and artifact checksums. Nexus search makes use of the industry standard for repository indexes, the Nexus Index format, and Nexus will automatically download a Nexus index from all remote repositories which create a Nexus index. Nexus will also automatically expose a Nexus index for any hosted repositories you create.

Scheduled Tasks

Nexus Open Source has the concept of scheduled tasks

  • periodic jobs which take care of various repository management tasks such as deleting old snapshots, evicting unused items, and publishing repository indexes.

REST Services

Nexus Open Source is based on a series of REST services, and when you are using the Nexus web front-end UI, you are really just interacting with a set of REST service. Because of this open architecture, you can leverage the REST service to create custom interactions or to automate repository management with your own scripts.

Nexus Plugins

Nexus Open Source provides a rich API for extension in the form of Nexus Plugins. When you write a Nexus Plugin, you can customize REST services, the Nexus UI, repository formats, or write components that can intercept requests and add new capabilities to the platform. The plugin API which you have access to in Nexus Open Source is the same plugin API that is used to implement value-added features available in Nexus Professional.

Integration with m2eclipse

When you use Nexus as a repository manager it creates indexes that support some of the next-generation tools available in m2eclipse - Sonatype’s Maven plugin for the Eclipse IDE. If you publish new artifacts and archetypes to Nexus, they are immediately available to m2eclipse project creation wizards and are included in m2eclipse search results.

Nexus Open Source License

Nexus Open Source is available under the GNU Affero General Public License version 3 (AGPLv3). The text of this license is available from the Open Source Initiative (OSI) here: http://opensource.org/licenses/agpl-v3.html

The Nexus Indexer is made available under the Eclipse Public License -v 1.0. The text of this license is available from the Open Source Initiative (OSI) here: http://www.opensource.org/licenses/eclipse-1.0.php

Nexus Professional

Nexus Professional was designed to meet the needs of the enterprise. It is a central point of access to external repositories which provides the necessary controls to make sure that only approved artifacts enter into your software development environment. It is also a central distribution point with the intelligence required to support the decision that go into making quality software. The extensibility provided by the custom metadata plugin coupled with REST services only available in Nexus Professional also lay the foundation for highly complex interactions within the enterprise. Once you start to use the workflow and decision support features of Nexus Professional, you will start to see it as the “assembly line” - the central collaboration point for your software development efforts.

Nexus Professional Features

Nexus Procurement Suite

Consider the default behavior of a proxy repository. Any developer can reference any artifact stored in a remote repository and cause Nexus to retrieve the artifact from the remote repository and serve back to a developer. Very often a company might want to control the set of artifacts which can be referenced in a proxy repository. Maybe the company has unique security requirements which require every third-party library to be subjected to a rigorous security audit before they can used. Or, maybe another company has a legal team which needs to verify that every artifact referenced by your software adheres to an inflexible set of license guidelines. The Nexus Procurement Suite was design to give organization this level of control over the artifacts that can be served from Nexus.

Nexus Staging Suite

When was the last time you did a software release to a production system? Did it involve a QA team that had to sign-off on a particular build? What was the process you used to redeploy a new build if QA found a problem with the system at the last minute? Because few organizations use a mature process to manage binary software artifacts, there is little in the way of infrastructure designed to keep track of the output of a build. The Nexus Staging Suite changes this by provide workflow support for binary software artifacts. If you need to create a release artifact and deploy it to a hosted repository, you can use the Staging Suite to post a collection of related, staged artifacts which can be tested, promoted, or discarded as a unit. Nexus keeps track of the individuals that are involved in a staged, managed release and can be used to support the decisions that go into producing quality software.

Hosting Project Web Sites

Nexus Professional is a publishing destination for project web sites. While you very easily generate a project web site with Maven, without Nexus, you will need to set up a WebDAV server and configure both your web server and build with the appropriate security credentials. With Nexus, you can deploy your project’s web site to the same infrastructure that hosts the project’s build output. This single destination for binaries and documentation helps to minimize the number of moving parts in your development environment. You don’t have to worry about configuring another web server or configuring your builds to distribute the project site using a different protocol, you simple point your project at Nexus and deploy the project site.

Support for OSGi Repositories

Instead of just supporting Maven repositories, Nexus Professional supports OSGi Bundle repositories and P2 repositories for those developers who are targetting OSGi or the Eclipse platform. Just like you can proxy, host, and group Maven repositories, Nexus Professional allows you to do the same with OSGi repositories.

Enterprise LDAP Support

Nexus Professional offers LDAP support features for enterprise LDAP deployments including detailed configuration of cache parameters, support for multiple LDAP servers and backup mirrors, the ability to test user logins, support for common user/group mapping templates, and the ability to support more than one schema across multiple servers.

Support for Atlassian Crowd

If your organization uses Atlassian Crowd, Nexus Professional can delegate authentication and access control to a Crowd server and map Crowd groups to the appropriate Nexus roles.

The User Account Plugin

When you are running a large, public instance of Nexus, it is often very useful to allow users to sign up for an account without the assistance of an administrator. Nexus Professional’s User Account plugin allows for just this. With this plugin activate, a new user simply has to fill out a simple form and type in letters from a CAPTCHA. Once a user has signed up for Nexus, Nexus will then send an email with a validation link. If you are working in an environment with hundreds or thousand of users the user account plugin will allow you to support the tool without having to create logins for each individual user.

Maven Settings Management

Nexus Professional along with the Nexus Maven Plugin allow you to manage Maven Settings. Once you have developed a Maven Settings template, developers can then connect to Nexus Professional using the Nexus Maven plugin which will take repsonsibility for downloading a Maven Settings file from Nexus and replacing the existing Maven Settings on a local workstation.

Support for Artifact Bundles

When software is deployed to the Maven Central repository, it is deployed as a signed artifact bundle. Nexus Professional’s Staging Suite allows you to upload artifact bundles to a staged repository.

Artifact Validation and Verification

The software artifacts you download from a remote repository are often signed with PGP signatures. Nexus Professional will make sure that these PGP signature are valid and the procurement plugin defines a few other rules that can be applied to artifacts which are downloaded from remote repositories. Nexus Professional also defines an API which allows you to create your own custom verification rules.

Custom Repository Metadata

Nexus Professional provides a facility for user-defined, custom metadata. If you need to keep track of custom attributes to support approval workflow or to associate custom identifiers with software artifacts, you can use Nexus to define and manipulate custom attributes which can be associated with artifacts in a Nexus repository.

Nexus Professional License

Nexus Professional is made available under a commercial license for businesses. Is available for free for use in qualifying Open Source projects, and is available at a discount for select Non-profits.

Choosing a Nexus Edition

If you are wondering which edition is appropriate for your organization. The following sections outline some reasons for choosing either Nexus Open Source of Nexus Professional.

Use Nexus Open Source…

…if you are new to Repository Management

If you are new to repository management, you should pick up a copy of Nexus Open Source, and experiment with Hosted and Proxy repositories. You should get a sense of how Maven Settings are configured to retrieve artifacts from a single Repository Group, and you should download a copy of the free Nexus book - Repository Management with Nexus. Once you’ve familiarized yourself with Nexus Open Souce, you can easily upgrade to Nexus Professional by downloading and installing Nexus Professional. Nexus stores all of your repository data and configuration in a directory named sonatype-work which is separate from the Nexus application directory.

…if you are looking for more stability and control

If you depend directly on public repositories such as the Maven Central repository or the various repositories maintained by organizations like Codehaus or the Apache Software Foundation, you rely on these servers to be available to your developers 100% of the time. If a public repository goes down for maintenance, so does your development process. With a local proxy of Maven artifacts, you buy yourself a stable, isolated build. Even if a public repositories becomes unavailable, you will still be able to build your software against artifacts cached in your own Nexus installation.

…if you need to manage internal software distribution

If your organization needs to support collaboration between internal teams, you can use Nexus to support the distribution of internal software. With Nexus, sharing components between internal groups is as easy as adding a dependency from Maven Central. Just publish a JAR to Nexus, configure the appropriate repositories groups and inform others in our organization of the Maven coordinates. Using a repository management doesn’t just make it easier to proxy external software artifacts, it makes it easier to share internal artifacts.

…if you need an intelligent local proxy

Many developers run Nexus on a local workstation as a way to gain more control over the repositories used by Nexus. This is also a great way to start evaluating Nexus. Download and install Nexus on your local workstation and point your Maven settings at http://localhost:8081/nexus. When you need to add a new repository, all you need to do is change the configuration of your local Nexus installation.

…if you need to integrate with an LDAP server

If you need to integrate Nexus with an an LDAP server, download Nexus Open Source. Nexus provides documented integration with popular LDAP servers such as OpenLDAP, Microsoft’s Active Directory Server, and any other directory product which implements the LDAP standard.

Use Nexus Professional…

…if you are looking for Professional Support

When you purchase Nexus Professional, you are purchasing one year of support from the team that created the industry-standard in repository management. With Nexus Professional, you not only get a capable repository manager, you get the peace of mind that help is just a phone call away. Sonatype also offers an array of implementation and migration services for organizations looking for an extra level of assistance. Contact Sonatype Sales for more information, call +1 (888) 866-2836.

…if you need a repository manager that can support release and quality assurance decisions:: Nexus Professional’s Staging Suite can track the staatus of a software release and make sure that different decision makers are notified and supported during a software release. If you are looking for a repository manager that can automate and support software releases, download Nexus Professional and start learning about Staged repositories and Staging Rulesets. When you start using Nexus Professional, your operations, quality assurance, and development teams can use the repository manager as a central point of collaboration.

…if you need more control over external artifacts

If you need more control over which external artifacts can be referenced and used in internal projects, you will need to use the Nexus Procurement Suite which is a part of Nexus Professional. While repositories like Maven Central are a great convenience, allowing your developers carte blanche access to any external library is often unacceptable in today’s legal and regulatory environment. Nexus Professional’s Procurement Suite allows you to enforce standards for external libraries. If you want to ensure that every dependency is evalautated for security or license compliance, download Nexus Professional.

…if you develop software for an Open Source project

Are you developing an open source project? If so, most open source projects qualify for a free Nexus Professional license. Open source projects can qualify for a free Professional license, or they can take advantage of free Nexus Professional hosting on http://oss.sonatype.org. Sonatype is very committed to supporting the development of quality open source and this is our way of giving back to the community.

…if you are developing and deploying to OSGi platforms

If you are developing OSGi components using OBR repositories, or if you are developing OSGi components using the P2 repository format, you will need to use the OSGi support available in the Nexus Professional distribution. Nexus Professional supports a wider array of repository formats than Nexus Open Source. As the industry moves toward OSGi as a standard, you should be using a product which supports these emerging standards as well as the existing repository formats used by millions of developers.

…if you need to integrate with Enterprise-level Security (LDAP and Crowd):: If you need to integrate Nexus with an Atlassian Crowd server or an enterprise LDAP deployment involving multiple servers or multiple LDAP schemas, download Nexus Professional. While Nexus Open Source provides extension points for writing custom security realms, Nexus Professional provides solid LDAP and Crowd support for the large, mission-critical LDAP deployments. If you need to support LDAP failover and federation, use Nexus Professional.

Comparing Nexus Open Source and Nexus Professional Features

The following table summarizes the differences between Nexus Open Source and Nexus Professional:

figs/web/nx-open-vs-pro-datasheet-4.png

History of Nexus

Proximity in December 2005 as he was trying to find a way to isolate his own systems from an incredibly slow ADSL connection provided by a Hungarian ISP. Proximity started as a simple web application to proxy artifacts for a small organization with connectivity issues. Creating a local on-demand cache for Maven artifacts from the Maven Central repository gave an organization access to the artifacts on the Maven Central Repository, but it also made sure that these artifacts weren’t downloaded over a very slow ADSL connection used by a number of developers. In 2007,

Sonatype asked Tamas to help create a similar product named Nexus. Nexus is currently considered the logical next step to Proximity. Nexus currently has an active development team, and portions of the indexing code from Nexus are also being used in m2eclipse.

Repository Management

Repository Management

Repository managers serve two purposes: they act as highly configurable proxies between your organization and the public Maven repositories and they also provide an organization with a deployment destination for its own generated artifacts. Just as Source Code Management (SCM) tools are designed to manage source artifacts, Repository Managers have been designed to manage and track external dependencies and artifacts generated by your build. They are an essential part of any enterprise or open-source software development effort, and they enable greater collaboration between developers and wider distribution of software.

Proxying Public Repositories

Proxying and caching a remote public repository can speed up your builds by reducing redundant downloads over the public Internet. If a developer in your organization needs to download version 2.5 of the Spring Framework and you are using Nexus, the dependencies (and the dependency’s dependencies) only need to be downloaded from the remote repository once.

With a high-speed connection to the Internet this might seem like a minor concern, but if you are constantly asking your developers to download hundreds of megabytes of third-party dependencies, the real cost savings are going to be the time it takes Maven to check for new versions of dependencies and to download dependencies over the public Internet.

Proxying and serving Maven dependencies from a local repository cache can save you hundreds of HTTP requests over the public Internet, and, in very large multi-module projects, this can shave minutes from a build.

Managing Releases and Snapshots

If your project is relying on a number of SNAPSHOT dependencies, Maven will need to regularly check for updated versions of these snapshots. Depending on the configuration of your remote repositories, Maven will check for SNAPSHOT updates periodically, or it might be checking for SNAPSHOT updates on every build. When Maven checks for a snapshot update it needs to interrogate the remote repository for the latest version of the SNAPSHOT dependency. Depending on your connection to the public Internet and the load on the Maven Central repository, a SNAPSHOT update can add seconds to your project’s build for each SNAPSHOT dependency you rely upon.

When you host a local repository proxy with Nexus, you reduce the amount of time it takes for Maven to check for a newer version as your build interacts with a local repository cache. If you develop software with SNAPSHOT dependencies, using a local repository manager will save you a considerable amount of time, your 5-10 second SNAPSHOT update checks against the public central repository are going to execute in hundreds of milliseconds (or less) when they are executed against a local resource.

Getting Control of Dependencies

In addition to the simple savings in time and bandwidth, a repository manager provides an organization with control over what is downloaded by Maven. You can include or exclude specific artifacts from the public repository, and having this level of control over what is downloaded from the Maven Central repository is a prerequisite for many organizations which have a need for strict standards for the quality and security of the dependencies used in an enterprise system.

If you want to standardize on a specific version of a dependency like Hibernate or Spring you can enforce this standardization by only providing access to a specific version of an artifact in Nexus. You might be concerned with making sure that every external dependency has a license compatible with your legal standards for adopting and integrating open source libraries. If you are producing an application which is distributed, you might want to make sure that no one inadvertently adds a dependency on a third-party library covered under a copy-left license like the GPL. All of this is possible with Nexus.

Repository managers are a central point of access to external binary software artifacts and dependencies your system relies upon. Nexus provides a level of control that is essential when you are trying to track and manage the libraries and frameworks your software depends upon.

A Nexus for Collaboration

Aside from the benefits of mediating access to remote repositories, a repository manager also provides an important platform for collaborative software development. Unless you expect every member of your organization to download and build every single internal project from source, you will want to provide a mechanism for developers and departments to share binary artifacts (both SNAPSHOTs and releases) for internal software projects. Internal groups often consume the APIs and systems which are generated by other internal groups, when you adopt Nexus as a deployment platform for internal artifacts, you can easily share components and libraries between groups of developers.

Nexus provides you with a deployment target for your software components. Once you install Nexus, you can start using Maven to deploy snapshots and releases to internal repositories which can then be combined with other repositories in repository groups. Over time, this central deployment point for internal projects becomes the fabric for collaboration between different development teams and operations. Nexus is the secret ingredient that allows an organization to scale its development effort without sacrificing agility.

What is a Repository?

Maven developers are familiar with the concept of a repository: a collection of binary software artifacts and metadata stored in a defined directory structure which is used by clients such as Apache Ivy to retrieve binaries during a build process. In the case of the Maven repository, the primary type of binary artifact is a JAR file containing Java bytecode, but there is no limit to what type of artifact can be stored in a Maven repository. For example, one could just as easily deploy documentation archives, source archives, Flash libraries and applications, or Ruby libraries to a Maven repository. A Maven repository provides a platform for the storage, retrieval, and management of binary software artifacts and metadata.

In Maven, every software artifact is described by an XML document called a Project Object Model (POM). This POM contains information that describes a project and lists a project’s dependencies - the binary software artifacts which a given component depends upon for successful compilation or execution.

When Maven downloads a dependency from a repository, it also downloads that dependency’s POM. Given a dependency’s POM, Maven can then download any other libraries which are required by that dependency. The ability to automatically calculate a project’s dependencies and transitive dependencies is made possible by the standard and structure set by the Maven repository.

Maven and other tools such as Ivy which interact with a repository to search for binary software artifacts, model the projects they manage, and retrieve software artifacts on-demand from a repository. When you download and install Maven without any customization, Maven will retrieve artifacts from a Maven Central repository which serves millions of Maven users every single day. While you can configure Maven to retrieve binary software artifacts from a collection of mirrors, the best-practice is to install Nexus and use it to proxy and cache the contents of Central on your own network. <indexterm>

In addition to Central, there are a number of major organizations such as Redhat, Sun Microsystems, and Codehaus which maintain separate repositories.

While this might seem like a simple, obvious mechanism for distributing artifacts, the Java platform existed for several years before the Maven project created a formal attempt at the first repository for Java artifacts. Until the advent of the Maven repository in 2002, a project’s dependencies were gathered in a manual, ad-hoc process and were often distributed with a project’s source code. As applications grew more and more complex, and as software teams developed a need for more complex dependency management capabilities for larger enterprise applications, Maven’s ability to automatically retrieve dependencies and model dependencies between components became an essential part of software development.

Release and Snapshot Repositories

A repository stores two types of artifacts: releases and snapshots. Release repositories are for stable, static release artifacts and snapshot repositories are frequently updated repositories that store binary software artifacts from projects under constant development.

While it is possible to create a repository which serves both release and snapshot artifacts, repositories are usually segmented into release or snapshot repositories serving different consumers and maintaining different standards and procedures for deploying artifacts. Much like the difference between a production network and a staging network, a release repository is considered a production network and a snapshot repository is more like a development or a testing network. While there is a higher level of procedure and ceremony associated with deploying to a release repository, snapshot artifacts can be deployed and changed frequently without regard for stability and repeatability concerns.

The two types of artifacts managed by a repository manager are:

Release

A release artifact is an artifact which was created by a specific, versioned release. For example, consider the 1.2.0 release of the commons-lang library stored in the Maven Central repository. This release artifact, commons-lang-1.2.0.jar, and the associated POM, commons-lang-1.2.0.pom, are static objects which will never change in the Maven Central repository. Released artifacts are considered to be solid, stable, and perpetual in order to guarantee that builds which depend upon them are repeatable over time. The released JAR artifact is associated with a PGP signature, an MD5 and SHA checksum which can be used to verify both the authenticity and integrity of the binary software artifact.

Snapshot

Snapshot artifacts are artifacts generated during the development of a software project. A Snapshot artifact has both a version number such as “1.3.0” or “1.3” and a timestamp in its name. For example, a snapshot artifact for commons-lang 1.3.0 might have the name commons-lang-1.3.0-20090314.182342-1.jar the associated POM, MD5 and SHA hashes would also have a similar name. To facilitate collaboration during the development of software components, Maven and other clients which know how to consume snapshot artifacts from a repository also know how to interrogate the metadata associated with a Snapshot artifact to retrieve the latest version of a Snapshot dependency from a repository.

A project under active development produces SNAPSHOT artifacts that change over time. A release is comprised of artifacts which will remain unchanged over time.

Repository Coordinates

Repositories and tools like Maven know about a set of coordinates including the following components: groupId, artifactId, version, and packaging. This set of coordinates is often referred to as a GAV coordinate which is short for “Group, Artifact, Version coordinate”. The GAV coordinate standard is the foundation for Maven’s ability to manage dependencies. Four elements of this coordinate system are described below:

groupId

A group identifier groups a set of artifacts into a logical group. Groups are often designed to reflect the organization under which a particular software component is being produced. For example, software components being produced by the Maven project at the Apache Software Foundation are available under the groupId org.apache.maven.

artifactId

An artifact is an identifier for a software component. An artifact can represent an application or a library; for example, if you were creating a simple web application your project might have the artifactId “simple-webapp”, and if you were creating a simple library, your artifact might be “simple-library”. The combination of groupId and artifactId must be unique for a project.

version

The version of a project follows the established convention of Major, Minor, and Point release versions. For example, if your simple-library artifact has a Major release version of 1, a minor release version of 2, and point release version of 3, your version would be 1.2.3. Versions can also have alphanumeric qualifiers which are often used to denote release status. An example of such a qualifier would be a version like “1.2.3-BETA” where BETA signals a stage of testing meaningful to consumers of a software component.

packaging

Maven was initially created to handle JAR files, but a Maven repository is completely agnostic about the type of artifact it is managing. Packaging can be anything that describes any binary software format including ZIP, SWC, SWF, NAR, WAR, EAR, SAR.

Addressing Resources in a Repository

Tools designed to interact Maven repositories translate artifact coordinates into a URL which corresponds to a location in a Maven repository. If a tool such as Maven is looking for version 1.2.0 of the commons-lang JAR in the group org.apache.commons, this request is translated into:

<repoURL>/org/apache/commons/commons-lang/1.2.0/commons-lang-1.2.0.jar

Maven would also download the corresponding POM for commons-lang 1.2.0 from:

<repoURL>/org/apache/commons/commons-lang/1.2.0/commons-lang-1.2.0.pom

This POM may contain references to other dependencies which would then be retrieved from the same repository using the same URL patterns.

The Maven Central Repository

The most useful Maven repository is the Maven Central Repository. The Maven Central repository contains almost 90,000 software artifacts occupying around 70 GB of disk space. You can look at Central as an example of how Maven repositories operate and how they are assembled. Here are some of the properties of release repositories such as the Maven Central repository:

Artifact Metadata

All software artifacts added to Central require proper metadata including a Project Object Model (POM) for each artifact which describes the artifact itself, and any dependencies that software artifact might have.

Release Stability

Once published to the Maven Central repository, an artifact and the metadata describing that artifact never change. This property of release repositories guarantees that projects which depend on releases will be repeatable and stable over time. While new software artifacts are being published to central every day, once an artifact is assigned a release number on Central, there is a strict policy against modifying the contents of a software artifact after a release.

Repository Mirrors

Central is a public resource, and it is currently used by the millions of developers who have adopted Maven and the tools that understand how to interact with the Maven repository structure. There are a series of mirrors for the Central repository which are constantly synchronized with Central. Users are encouraged to query central for project metadata and cryptographic hashes and they are encouraged to retrieve the actual software artifacts from one of Central’s many mirrors. Tools like Nexus are designed to retrieve metadata from Central and artifact binaries from mirrors.

Artifact Security

The Maven Central repository contains cryptographic hash cryptographic hashes and PGP signatures which can be used to verify the authenticity and integrity of software artifacts served from Central or one of the many mirrors of Central.

What is a Repository Manager

If you use Maven, you are using a repository to retrieve artifacts and Maven plugins. In fact, Maven used a Maven repository to retrieve core plugins that implement the bulk of the features used in your builds. Once you start to rely on repositories, you realize how easy it is to add a dependency on an open source software library available in the Maven Central repository, and you might start to wonder how you can provide a similar level of convenience for your own developers. When you install a repository manager, you are bringing the power of a repository like Central into your organization, you can use it to proxy Central, and host your own repositories for internal and external use. In this section, we discuss the core functionality which defines what a repository manager does.

Put simply, a repository manager provides two core features:

  • The ability to proxy a remote repository and cache artifacts saving both bandwidth and time required to retrieve a software artifact from a remote repository, and

  • The ability the host a repository providing an organization with a deployment target for software artifacts.

In addition to these two core features, a repository manager also allows you to manage binary software artifacts through the software development lifecycle, search and catalog software artifacts, audit development and release transactions, and integrate with external security systems such as LDAP. The following sections define the feature sets of Nexus Open Source and Nexus Professional.

Core Capabilities of a Repository Manager

The base-line features of a repository manager are a description of the core capabilities of Nexus Open Source. Nexus Open Source provides for the:

Management of Software Artifacts

A repository manager is able to manage packaged binary software artifacts. In Java development, this would include JARs containing bytecode, source, or javadoc. In other environments, such as Flex, this would include any SWCs or SWFs generated by a Flex build.

Management of Software Metadata

A repository manager should have some knowledge of the metadata which describes artifacts. In a Maven repository this would include project coordinates (groupId, artifactId, version, classifier) and information about a given artifact’s releases.

Proxying of External Repositories

Proxying an external repository yields more stable builds as the artifacts used in a build can be served to clients from the repository manager’s cache even if the external repository becomes unavailable. Proxying also saves bandwidth and time as checking for the presence of an artifact on a local network is often orders of magnitude faster than querying a heavily loaded public repository

Deployment to Hosted Repositories

Organizations which deploy internal snapshots and releases to hosted repositories have an easier time distributing software artifacts across different teams and departments. When a department or development group deploys artifacts to a hosted repository, other departments and development groups can develop systems in parallel, relying upon dependencies served from both release and snapshot repositories.

Searching an Index of Artifacts

When you collect software artifacts and metadata in a repository manager, you gain the ability to create indexes and allow users and systems to search for artifacts. With the Nexus index, an IDE such as Eclipse has almost instantaneous access to the contents of all proxy repositories (including the Central repository) as well as access to your own internal and 3rd party artifacts. While the Central repository transformed the way that software is distributed, the Nexus index format brings the power of search to massive libraries of software artifacts.

Infrastructure for Artifact Management

A repository manager should also provide the appropriate infrastructure for managing software artifacts and a solid API for extension. In Nexus, Sonatype has provided a plugin API which allows developers to customize both the behavior, appearance, and functionality of the tool.

Additional Features of a Repository Manager

Once you adopt the core features of a repository manager, you start to view a repository manager as a tool which enables more efficient collaboration between development groups. Nexus Professional builds upon the foundations of a repository manager and adds capabilities such as Procurement and Staging.

Managing Project Dependencies

Many organizations require some level of oversight over the open source libraries and external artifacts that are let into an organization’s development cycle. An organization could have specific legal or regulatory constraints which requires every dependency to be subjected to a rigorous legal or security audit before it is integrated into a development environment. Another organization might have an architecture group which needs to make sure that a large set of developers only has access to a well-defined list of dependencies or specific versions of dependencies. Using the Procurement features of Nexus Professional, managers and architecture groups have the ability to allow and deny specific artifacts from external repositories.

Managing a Software Release

Nexus Professional adds some essential workflow to the process of staging software to a release repository. Using Nexus Professional, developers can deploy to a staging directory which can trigger a message to a Release Manager or to someone responsible for QA. Quality assurance (or a development manager) can then test and certify a release having the option to promote a release to the release repository or to discard a release if it didn’t meet release standards. Nexus Professional’s staging features allow managers to specify which personnel are allowed to certify that a release can be promoted to a release repository giving an organization more control over what software artifacts are released and who can release them.

Integration with LDAP

Nexus integrates with an LDAP directory, allowing an organization to connect Nexus to an existing directory of users and groups. Nexus authenticates users against an LDAP server and provides several mechanisms for mapping existing LDAP groups to Nexus roles.

Advanced Security

Using Nexus Professional, an organization can define a master User Password Encryption Key. Each user will be given a separate Maven settings file with an encrypted password using the Maven Nexus plugin. When users interact with Nexus, Nexus uses the User Password Encryption Key to decrypt a user’s Nexus credentials avoiding the need to send an easily compromised plain-text password over the network.

Settings Templates

Nexus Professional allows you to define Maven settings templates for developers. Developers can then automatically receive updates to Maven settings (~/.m2/settings.xml) using the Maven Nexus plugin. The ability to define Maven settings templates and to distribute customized Maven settings files to developers makes it easy for an organization to change global profiles or repository configuration without relying on developers to manually install a new settings file in a development environment.

Support for Multiple Repository Formats

Nexus Professional supports the p2 and the OSGi Bundle repository format used by the new Eclipse provisioning platform and OSGi developers. You can use the p2 plugin to consolidate, provision, and control the plugins that are being used in an Eclipse IDE. Using Nexus procurement, repository groups, and proxy repositories to consolidate multiple plugin repositories, an organization can use Nexus Professional to standardize the configuration of Eclipse IDE development environments.

Reasons to Use a Repository Manager

Here are a few reasons why using a repository manager is an imperative. While most people wouldn’t even think of developing software without the use of a source code control system like Subversion or Perforce, the concept of using a repository manager is still something that needs development. There are many who use Maven for years without realizing the benefits of using a repository manager. This section was written as an attempt to capture some of the benefits of using a repository manager.

Speed Up Your Builds

When you run your multi-module project in Maven, how do you think Maven knows if it needs to update plugins or snapshot dependencies? It has to make a request for each artifact it needs to test. Even if nothing has changed, if your project depends on a few SNAPSHOTs or if you don’t specify plugin version, Maven might have to make tens to hundreds of requests to a remote repository. All of these requests over the public Internet add up to real, wasted, time. I’ve seen complex builds cut build time by 75% after installing a local instance of Nexus. You are wasting time better spent coding waiting for your build to needlessly interrogate a remote Maven repository.

Save Bandwidth

The larger the organization, the more critical bandwidth savings can be. If you have thousands of developers regularly wasting good bandwidth to download the same files over and over again, using a repository manager to keep a local cache is going to save you a good deal of bandwidth. Even for smaller organizations with limited budgets for connectivity and IT operations, having to deal with a set of developers maxing out your connection to the Internet to download the same things over and over again seems backwards.

Ease the Burden on Central

Running the Maven Central repository is no short order. It ain’t cheap to serve the millions of requests and Terabytes of data required to satisfy the global demand for software artifacts from the Maven Central repository. Something as simple as installing a repository manager at every organization that uses Maven would likely cut the bandwidth requirements for Central by at least half. If you have more than a couple developers using Maven, install a repository manager for the sake of keeping Central available and in business.

Gain Predictability and Scalability

How often in the past few years has your business come to a crashing halt because of an outage? Depending on Central for your day to day operations also means that you depend on having Internet connectivity (and on the fact the Central will remain available 24/7). While Sonatype is confident in its ability to keep Central running 24/7, you should take some steps of your own to make sure that your development team isn’t going to be surprised by some network outage on either end. If you have a local repository manager, like Nexus, you can be sure that your builds will continue to work even if you lose connectivity.

Control and Audit Dependencies and Releases

So, you’ve moved over to Maven (or maybe Ivy, Ivy reads the same repository), and you now have a whole room full of developers who feel empowered to add or remove dependencies and experiment with new frameworks. We’ve all seen this. We’ve all worked in places with a developer who might be more interested in experimenting than in working. It is unfortunate to say so, but there are often times when an architect, or an architecture group needs to establish some baseline standards which are going to be used in an organization. Nexus provides this level of control. If you need more oversight over the artifacts that are making it into your organization, take a look at Nexus. Without a repository manager, you are going to have little control over what dependencies are going to be used by your development team.

Deploy 3rd Party Artifacts

How do you deal with that one-off JAR from a vendor that is not open source, and not available on the Maven Central repository? You need to deploy these artifacts to a repository and configure your Maven instance to read from that repository. Instead of handcrafting some POMs, download Nexus and take the two or three minutes it is going to take to get your hands on a tool that can create such a repository from 3rd-party artifacts. Nexus provides an intuitive upload form that you can use to upload any random free-floating JAR that finds its way into your project’s dependencies.

Collaborate with Internal Repositories

Many organizations require every developer to checkout and build the entire system from source simply because they have no good way of sharing internal JARs from a build. You can solve a problem like this by splitting projects up and using Nexus as an internal repository to host internal dependencies.

For example, consider a company that has 30 developers split into three groups of 10, each group focused on a different part of the system. Without an easy way to share internal dependencies, a group like this is forced either to create an ad hoc filesystem-based repository or to build the system in its entirety so that dependencies are installed in every developer’s local repository.

The alternative is to separate the projects into different modules that all have dependencies on artifacts hosted by an internal Nexus repository. Once you’ve done this, groups can collaborate by exchanging compiled snapshot and release artifacts via Nexus. In other words, you don’t need to ask every developer to checkout a massive multi-module project that includes the entire organization’s code. Each group within the organization can deploy snapshots and artifacts to a local Nexus instance, and each group can maintain a project structure which includes only the projects it is responsible for.

Distribute with Public Repositories

If you are an open source project, or if you release software to the public, Nexus can be the tool you use to serve artifacts to external users. Think about it this way… When was the last time you cut a release for your software project? Assuming it wasn’t deployed to a Maven repository, you likely had to write some scripts to package the contents of the release, maybe someone special had to sign the release with a super-secret cryptographic key. Then, you had to upload it to some web server, and then make sure that the pages that describe the upload were themselves updated. Lots of needless complexity…

If you were using something like Nexus, which can be configured to expose a hosted repository to the outside world, you could use the packaging and assembly capabilities of Maven and the structure of the Maven repository to make a release that is more easily consumed. And, this isn’t just for JAR files and Java web applications; Maven repositories can host any kind of artifact. Nexus, and Maven repositories in general, define a known structure for releases. If you are writing some Java library, publishing it to your own Nexus instance serving a public repository will make it easier for people to start using your code right away.

Adopting a Repository Manager

This section talks about the stages of moving to a repository manager. Adopting a repository manager is not an all or nothing proposition, and there are various levels (or stages) of adoption that can be distinguished when approaching repository management. On one end of the adoption spectrum is the organization that installs a repository manager just to control and consolidate access to a set of remote repositories. On the other end of the spectrum is the organization which has integrated the repository manager into an efficient software development lifecycle, using it to facilitate decision points in the lifecycle, encouraging more efficient collaboration throughout the enterprise, and keeping detailed records to increase visibility into the software development process.

Stage Zero: Before Using a Repository Manager

While this isn’t a stage of adoption, Stage Zero is a description of the way software builds work in the absence of a repository manager. When a developer decides that a he needs a particular open source software component, he will download it from the component’s website, read the documentation, and find the additional software that his components rely on (referred to as “dependencies”). Once he has manually assembled a collection of dependencies from various open source project web sites and proprietary vendors, he will place all these components somewhere on the network so that he, his team members, the build script, the QA team, and the production support team can find it. At any time, other developers may bring in other components, sometimes with overlapping dependencies, placing them in different network locations. The instructions to bring all of these ad-hoc, developer-managed components libraries together in a software build process can become very complicated and hard to maintain.

Maven was introduced to improve this build process by introducing the concept of structured repositories from which the build scripts can retrieve the software components. In Maven language, these software components or dependencies are referred to as “artifacts”, a term which can refer to any generic software artifact including components, libraries, frameworks, containers, etc. Maven can identify artifacts in repositories, understand their dependencies, retrieve all that are needed for a successful build, and deploy its output back to repositories when done.

Developers using Maven without a repository manager find most of their software artifacts and dependencies in Maven Central. If they happen to use another remote repository or if they need to add a custom artifact, the solution, in Stage Zero, is to manually manipulate the files in a local repository and share this local repository with multiple developers. While this approach may yield a working build for a small team, managing a shared local repository doesn’t allow an organization to scale a development effort. There is no inherent control over who can set up a local repository, who can add to them or change or delete from them, nor are there tools to protect the integrity of these repositories.

That is, until Repository Managers were introduced.

Stage One: Proxying Remote Repositories

This is the easiest stage to understand both in terms of benefits to an organization and action required to complete this stage. All you need to do to start proxying a remote repository is to deploy Nexus and start the server with the default configuration. Configure your Maven clients to read from the Nexus public repository group, and Nexus will automatically retrieve artifacts from remote repositories, such as Maven Central, caching them locally.

Without a repository manager, your organization might have hundreds of developers independently downloading the same artifacts from public, remote repositories. With a repository manager, these artifacts can be downloaded once and stored locally. After Stage One, your builds run considerably faster than they did when you relied upon the Maven Central repository.

Once you’ve installed Nexus and you’ve configured all of your organization’s clients to use it as a single point of access to remote repositories, you begin to realize that it now provides you with a central configuration point for the artifacts used throughout your organization. Once you’ve started to proxy, you can start to think about using Nexus as a tool to control policy and what dependencies are allowed to be used in your organization. Nexus Professional provides a procurement plugin which allows for fine-grained control over which artifacts can be accessed from a remote repository. This procurement feature is described in more detail in the section which deals with Lifecycle Integration.

Stage Two: Hosting a Repository Manager

Once you have started to proxy remote repositories and you are using Nexus as a single, consolidated access point for remote repositories, you can start to deploy your own artifacts to Nexus hosted repositories. Most people approach repository management to find a solution for proxying remote repositories, and while proxying is the most obvious and immediate benefit of installing a repository manager, hosting internally generated artifacts tends to be the stage that has the most impact on collaboration within an organization.

To understand the benefits of hosting an internal repository, you have to understand the concept of managing binary software artifacts. Software development teams are very familiar with the idea of a source code repository or a source code management tool. Versioning control systems such as Subversion, Clearcase, Git, and CVS provide solid tools for managing the various source artifacts that comprise a complex enterprise application, and developers are comfortable checking source out from source control to build enterprise applications. However, past a certain point in the software development lifecycle, source artifacts are no longer relevant. A QA department trying to test an application or an Operations team attempting to deploy an application to a production network no longer needs access to the source artifacts. QA and Operations are more interested in the compiled end-product of the software development lifecycle: the binary software artifacts. A repository manager allows you to version, store, search, archive, and release binary software artifacts derived from the source artifacts stored in a source control system. A repository manager allows you to apply the same systematic operations on binary software artifacts which you currently apply to your source code.

When your build system starts to deploy artifacts to an internal repository, it changes the way that developers and development groups can interact with one another in an enterprise. Developers in one development group can code and release a stable version of an internal library, deploy this library to an internal Nexus release repository, and so share this binary artifact with another group or department. Without a repository manager managing internal artifacts, you have ad-hoc solutions and the organizational equivalent of "duct tape". How does the infrastructure group send a new library to the applications group without Nexus? Someone copies a file to a shared directory, and sends an email to the team lead. Organizations without repository managers are full of these ad-hoc processes that get in the way of efficient development and deployment.

With a repository manager, every developer and every development group within the enterprise understands and interacts with a common collaborative structure: the repository manager. Do you need to interact with the Commerce team’s new API? Just add a dependency to your project and Maven will retrieve the library from Nexus automatically.

One of the other direct benefits of deploying your own artifacts to a repository such as Nexus is the ability to quickly search the metadata and contents of those artifacts both via a web UI and through IDE integration tools such as m2eclipse. When you start to deploy internal artifacts you can synchronize all development groups to a common versioning and naming standard, and you can use the highly configurable authentication and role-based access controls to control which developers and which development groups can deploy artifacts to specific repositories or paths within a repository.

Stage Three: Continuous Collaboration

Developing this collaborative model further, if your application is being continuously built and deployed using a tool like Hudson, a developer can checkout a specific module from a large multi-module build and not have to constantly deal with the entire source tree at any given time. This allows a software development effort to scale efficiently. If every developer working on a complex enterprise application needs to checkout the entire source tree every time he or she needs to make a simple change to a small component, you are quickly going to find that building the entire application becomes a burdensome bottleneck to progress. The larger your enterprise grows, the more complex your application becomes, the larger the collective burden of wasted time and missed opportunities. A slow enterprise build prevents the quick turnaround or quick feedback loop that helps your developers maintain focus during a development cycle.

Once you are building with Maven, sharing binary artifacts with Nexus, continuously testing and deploying with Hudson, and generating reports and metrics with tools like Sonar, your entire organization gains a collaborative "central nervous system" that enables a more agile approach to software development.

Stage Four: Lifecycle Integration

Once you’ve configured a repository manager to proxy remote repositories and you are using a repository manager as an integration point between developers and departments, you start to think about the various ways your repository manager can be used to support the decisions that go into software development. You can start using the repository manager to stage releases and supporting the workflow associated with a managed release, and you can use the procurement features of a tool like Nexus Professional to give management more visibility into the origins, characteristics and open source licenses of the artifacts used during the creation of an enterprise application.

Nexus Professional enables organizations to integrate the management of software artifacts tightly with the software development lifecycle: Developer Onboarding, Provisioning, Compliance, Procurement, Enterprise Security, Staging and other capabilities that support the workflow that surrounds a modern software development effort.

Developer Onboarding

Using Nexus Professional’s support for Eclipse plugin repositories, Nexus can be used to dramatically reduce the time required to provision a new Eclipse environment for a new developer. Using Nexus’ p2 repository support, a developer’s IDE can be quickly configured from a set of Eclipse plugins managed and procured via Nexus Professional and delivered directly to the developer’s desktop.

Using Nexus Professional’s Maven Settings management feature and integrated security features you can configure a developer’s Maven settings by running a single, convenient Maven goal and downloading customized settings for a particular developer. When you use Maven and Nexus Professional together, developers can get up and running quickly, collaborating on projects that share common conventions without having to manually install dependencies in local repositories.

Provisioning

Using Nexus as an integration point between Engineering and Operations means that Engineering can be responsible for delivering solid, tested artifacts to Quality Assurance and Operations via a standard repository format. Often development teams are roped into the production deployment story and become responsible for building entire production environments within a build system. This conflates software engineering with system administration and blurs the line between Engineering and Operations. If you use Nexus as a end-point for releases from Engineering, Operations can then retrieve, assemble, and configure an application from tested components in the Nexus repository.

Compliance

Procurement, staging, and audit logs are all features which increase the visibility into who and what is involved with your software development effort. Using Nexus Professional, Engineering can create the reports and documents which can be used to facilitate discussions about oversight. Organizations subject to various regulations often need to produce a list of components involved in a software release. Legal departments often require a list of open source licenses being used in a particular software component, and managers often lack critical visibility into the software development process.

Procurement

The ease with which today’s developer can add a dependency on a new open source library and download this library from a Central repository has a downside. Organizations large and small are constantly wondering what open source libraries are being used in applications, and whether these libraries have acceptable open source licenses for distribution. The Procurement features of Nexus Professional give architects and management more oversight over the artifacts which are allowed into an organization. Using the Procurement features, a Nexus administrator or Procurement manager can allow or deny specific artifacts by group, version, or path. You can use the procurement manager as a firewall between your own organization’s development environment and the 95,000 artifacts available on the Maven Central repository.

Enterprise Security

Nexus’ LDAP integration allows an enterprise to map existing LDAP groups to Nexus roles and provides Nexus administrators with a highly configurable interface to control which individuals or groups have access to a fine-grained set of Nexus permissions.

Staging

Nexus Professional adds an important step to the software release workflow, adding the concept of a managed (or staged) release to a hosted repository. When a developer needs to perform a production release, Nexus Professional can isolate the artifacts involved in a release in a staged repository which can then be certified and tested. A manager or a quality assurance tester can then promote or discard a release. The staging feature allows you to specify the individuals that are allowed to promote a release and keeps an audit of who was responsible for testing, promoting, or discarding a software release.

Installing and Running Nexus

Downloading Nexus

There are two distributions of Nexus: Nexus Open Source and Nexus Professional. Nexus Open Source is a fully-featured repository manager which can be freely used, customized, and distributed under the GNU Affero General Public License (AGPL) Version 3. Nexus Professional is a distribution of Nexus with features that are relevant to large enterprises and organizations which require complex procurement and staging workflows in addition to more advanced LDAP integration, Atlassian Crowd support, and other development infrastructure. The differences between Nexus Open Source and Nexus Professional are explored in the previous chapter.

Downloading Nexus Open Source

Download Nexus Open Source from http://nexus.sonatype.org/download-nexus.html then download the appropriate Nexus Open Source distribution by clicking on the appropriate archive as shown in <xref linkend="fig-installing_open-source-dl-select" />. Nexus Open Source is available as a ZIP and a Gzip’d TAR file under the file names ${nexusopen.bundle.name}.zip and ${nexusopen.bundle.name}.tgz

figs/web/installing_open-source-dl.png
Figure 1. Downloading Nexus Open Source from nexus.sonatype.org
figs/web/installing_open-source-dl-select.png
Figure 2. Selecting the Nexus Open Source Distribution Download

Nexus Open Source can also be deployed as a web application in a servlet container like Jetty or Tomcat or an application server like Glassfish or JBoss. Instructions for installing Nexus as a WAR are found in <xref linkend="install-sect-as-a-war" />.

Downloading Nexus Professional

To download Nexus Professional, go to the Nexus Trial evaluation form.

Fill out the form and then check your email account for download instructions. After filling out a brief contact form and agreeing to the evaluation license, you will be sent an email with a link to download the Nexus Professional distribution. Nexus is available as a ZIP file under the file names ${nexus.bundle.name}.zip and ${nexus.bundle.name}.tgz

Installing Nexus

The following sections detail the installation process for both Nexus Open Source and Nexus Professional.

Nexus Prerequisites

Nexus Open Source and Nexus Professional only have one prerequisite, a Java Runtime Environment (JRE) compatible with Java 5 or higher. Nexus is most often run with the JRE that is bundled with a Java Development Kit (JDK) installation, and it can be run with the latest version of Sun’s JDK for Java 5 or Java 6. To download the latest release of the Sun JDK, go to http://developers.sun.com/downloads/, and download the latest Java 6 JDK or an older Java 5 JDK, either will work but Java 6 is recommended.

Installing Nexus Open Source

The following instructions are for installing Nexus Open Source as a stand-alone server. Nexus comes bundled with a Jetty instance which listens to all configured IP addresses on a host (0.0.0.0) and runs on port 8081 by default. If you would like to run Nexus Open Source as a web application in an existing application server or servlet container, please refer to the instructions in <xref linkend="install-sect-as-a-war" />.

Installing Nexus Open Source is straightforward. Unpack the Nexus web application archive in a directory. If you are installing Nexus on a local workstation to give it a test run, you can install it in your home directory or wherever you like; Nexus doesn’t have any hard coded directories, it will run from any directory. If you downloaded the ZIP

$ unzip ${nexusopen.bundle.name}.zip

And, if you download the GZip’d TAR archive, run:

$ tar xvzf ${nexusopen.bundle.name}.tgz
Note There are some known incompatibilities with the version of tar provided by Solaris and the gzip tar format. If you are installing Nexus on Solaris, you must use the GNU tar application, or you will end up with corrupted files.
Note If you are installing Nexus on a server, you might want to use a directory other than your home directory. On a Unix machine, this book assumes that Nexus is installed in /usr/local/${nexusopen.version.name} with a symbolic link /usr/local/nexus to the nexus directory. Using a generic symbolic link nexus to a specific version is a common practice which makes it easier to upgrade when a newer version of Nexus is made available.
$ sudo cp ${nexusopen.bundle.name}.tgz /usr/local
$ cd /usr/local
$ sudo tar xvzf ${nexusopen.bundle.name}.tgz
$ ln -s ${nexusopen.version.name} nexus

Although it isn’t required for Nexus to run, you may want to set an environment variable NEXUS_HOME in your environment which points to the installation directory of Nexus. This chapter will refer

The Nexus installation directory ${nexusopen.version.name} has a sibling directory named sonatype-work. This directory contains all of the repository and configuration data for Nexus and is stored outside of the Nexus installation directory to make it easier to upgrade to a newer version of Nexus. By default, this directory is always a sibling to the nexus installation directory; if you installed nexus in /usr/local directory would also contain a sonatype-work subdirectory containing all of the content and configuration. The location of the sonatype-work directory can be customized by altering the nexus-work

Installing Nexus Professional

The following instructions are for installing Nexus Professional as a stand-alone server. Nexus Professional is bundled with a Jetty instance which listens to all configured IP addresses on a host (0.0.0.0) and runs on port 8081 by default.

Installing Nexus is straightforward, unpack the Nexus web application archive in a directory. If you are installing Nexus on a local workstation to give it a test run, you can install it in your home directory or wherever you like; Nexus doesn’t have any hard coded directories, it will run from any directory. If you downloaded the ZIP

$ unzip ${nexus.bundle.name}.zip

And, if you download the GZip’d TAR archive, run:

$ tar xvzf ${nexus.bundle.name}.tgz

If you are installing Nexus on a server, you might want to use a directory other than your home directory. On a Unix machine, this book assumes that Nexus is installed in /usr/local/${nexus.version.name} with a symbolic link /usr/local/nexus to the nexus directory. Using a symbolic link nexus to a directory which holds a specific version of Nexus is a common practice that makes it easier to upgrade to a newer version of Nexus.

$ sudo cp ${nexus.bundle.name}.tgz /usr/local
$ cd /usr/local
$ sudo tar xvzf ${nexus.bundle.name}.tgz
$ ln -s ${nexus.version.name} nexus

Although it isn’t required for Nexus to run, you may want to set an environment variable NEXUS_HOME in your environment which points to the installation directory of Nexus. This chapter will refer to this ${nexus.version.name} has a sibling directory named sonatype-work. This directory contains all of the repository and configuration data for Nexus and is stored outside of the Nexus installation directory to make it easier to upgrade to a newer version of Nexus.

Upgrading Nexus

Since Nexus separates its configuration and data storage from the application, it is easy to upgrade an existing Nexus installation. To upgrade Nexus, unpack the Nexus archive in the directory which contains the existing Nexus installation. Once the archive is unpacked, the new Nexus application directory should be a sibling to your existing sonatype-work/ directory. If you have defined a symbolic link for the version of Nexus to use, change that to point at the new Nexus application directory. When you start the new instance of Nexus it will read the existing repository configuration from the sonatype-work/

Running Nexus

When you start Nexus, you are starting a web server on the default port of 0.0.0.0:8081. Nexus runs within a servlet container called Jetty and it is started with a native service wrapper called the Tanuki Java Service Wrapper. This service wrapper can be configured to run Nexus as a Windows service or a Unix daemon. To start Nexus, you will need to find the appropriate startup script for your platform. To see the list of available platforms, list the contents of the

The following example listing starts Nexus using the script for Mac you the available platforms, then we make the contents of the bin directory executable with chmod. The Mac OS X wrapper is started with a call to nexus start, and then we tail the wrapper.log in stating what IP address and port it is listening on.

$ cd /usr/local/nexus
$ ls ./bin/jsw/
conf/                linux-x86-64/        solaris-x86-32/
lib/                 macosx-universal-32/ windows-x86-32/
license/             macosx-universal-64/ windows-x86-64/
linux-ppc-64/        solaris-sparc-32/
linux-x86-32/        solaris-sparc-64/
$ chmod -R a+x bin
$ ./bin/jsw/macosx-universal-64/nexus start
Starting Nexus Repository Manager...
Started Nexus Repository Manager.
$ tail -f logs/wrapper.log
INFO  ... [ServletContainer:default] - SelectChannelConnector@0.0.0.0:8081

At this point, Nexus will be running and listening on all IP addresses (0.0.0.0) that are configured for the current host on port 8081. To use Nexus, fire up a web browser and type in the URL: http://localhost:8081/nexus

While we use "localhost" throughout this book, you may need to use the IP Loopback Address of "127.0.0.1" or the IP address assigned to the machine running Nexus. Click on the "Log In" link in the upper right-hand corner of the web page, and you should see the login dialog. THE DEFAULT NEXUS USERNAME AND PASSWORD IS "admin" AND "admin123".

figs/web/installation_default-admin.png
Figure 3. Default Nexus Administrative Credentials (admin/admin123)
figs/web/repository-manager_nexus-login.png
Figure 4. Nexus Application Window (default login/password is admin/admin123)

Post-Install Checklist

Nexus ships with some default passwords and settings for repository indexing that need to be changed for your installation to be useful (and secure). After installing and running Nexus, you need to make sure that you complete the following tasks:

Step 1: Change the Administrative Password and Email Address

The administrative password defaults to admin123. The first thing you should do to your new Nexus installation is change this password. To change the administrative password login as "admin" with the password "admin123", and click on Change Password under the Security menu in the left-hand side of the browser window. For more detailed instructions, see <xref linkend="using-sect-changing-password" />.

Step 2: Configure the SMTP Settings

Nexus can send username and password recovery emails, to enable this feature, you will need to configure Nexus with a SMTP Host and Port as well as any necessary authentication parameters that Nexus needs to connect to the mail server. To configure the SMTP settings, load the server configuration dialog shown in <xref linkend="fig-nexus-server-config" />.

Step 3: Enable Remote Index Downloads

Nexus ships with three important proxy repositories for the Maven Central repository, Apache Snapshot repository, and the Codehaus Snapshot repository. Each of these repositories contains thousands (or tens of thousands) of artifacts and it would be impractical to download the entire contents of each. To that end, most repositories maintain an index which catalogs the entire contents and provides for fast and efficient searching. Nexus uses these remote indexes to search for artifacts, but we’ve disabled the index download as a default setting. To download remote indexes:

  1. Click on Repositories under the Administration menu in the left-hand side of the browser window.

  2. Select each of the three proxy repositories and change Download Remote Indexes to true in the Configuration tab. You’ll need to load the dialog shown in <xref linkend="fig-repo-config" /> for each of the three repositories.

This will trigger Nexus to re-index these repositories, during which the remote index files will be downloaded. It might take Nexus a few minutes to download the entire index, but once you have it, you’ll be able to search the entire contents of the Maven repository.

Once you’ve enabled remote index downloads, you still won’t be able to browse the complete contents of a remote repository. Downloading the remote index allows you to search for artifacts in a repository, but until you download those artifacts from the remote repository they will not show in the repository tree when you are browsing a repository. When browsing a repository, you will only be shown artifacts which have been downloaded from the remote repository.

Step 4: Change the Deployment Password

The deployment user’s password defaults to deployment123. Change this password to make sure that only authorized developers can deploy artifacts to your Nexus installation. To change the deployment password: log in as an administrator, click on Security to expand the Security menu, then click on Users. You should then see a list of users. Right-click on the deployment user and select "Set Password".

Step 5: Install Professional License (Nexus Professional Only)

If you are running Nexus Professional and you have purchased a license from Sonatype, you will need to upload your license. This license will be emailed to you after you have purchased Nexus Professional from http://store.sonatype.com. To load the License tab, click on Licensing under the Enterprise menu in the Nexus application menu. For more information about installing a Nexus Professional license file, see <xref linkend="installing-sect-licensing" />.

Step 6: If necessary, set the LANG Environment Variable

If your Nexus instance needs to store configuration and data using an international character set, you should set the LANG environment variable. The Java Runtime will adapt to the value of the LANG environment variable and ensure that configuration data is saved using the appropriate character type. If you are starting Nexus as a service, place this environment variable in the startup script found in /etc/init.d/nexus. For more information about locale settings in Ubuntu read https://help.ubuntu.com/community/Locale

Configuring Nexus as a Service

When installing Nexus, you will often want to configure Nexus as a service. If you are on Windows, the Nexus distribution includes binaries that can work with the Windows Services subsystem and if you are on another platform such as GNU/Linux Nexus also includes scripts that can be configured to start Nexus as a service. The following sections provide instructions for configuring Nexus as a service.

Startup Scripts for GNU/Linux

You can configure Nexus to start automatically, by copying the nexus script to the /etc/init.d directory. On a GNU/Linux system (tested with Redhat, Fedora, Ubuntu, or CentOS) perform the following operations as the root user:

  1. Make the /etc/init.d/nexus script executable - chmod 755 /etc/init.d/nexus

  2. Edit this script changing the following variables:

    1. Change APP_NAME

    2. Change APP_LONG_NAME to "Sonatype Nexus"

    3. Add a variable NEXUS_HOME which points to your Nexus installation directory

    4. Add a variable PLATFORM which contains either linux-x86-32, linux-x86-64, or linux-ppc-64

  3. Change PIDDIR to /var/run

  4. Add a JAVA_HOME variable which points to your local Java installation

  5. (Optional) Set the RUN_AS_USER to "nexus". If you do this, you will need to:

    1. Create a nexus user

    2. Change the Owner and Group of your nexus install directory to nexus

Note If you set the "RUN_AS_USER" variable, you’ll have to change the "pid" directory to point to a directory where this user has read/write permissions. In most Linux distributions, /var/run is only writable by root. The properties that would need to be added to customize the PID file location is "wrapper.pid". For more information about this property and how it would be configured in wrapper.conf, see: http://wrapper.tanukisoftware.com/doc/english/properties.html
figs/web/installing_bin-dir-l32.png
Figure 5. Script Directory for 32-bit GNU/Linux

At the end of this you should have a file in /etc/init.d/nexus which starts with a series of configuration properties which look something like this (assuming that you’ve installed Nexus in /usr/local/nexus and that you have Java installed in /usr/java/latest

JAVA_HOME=/usr/java/latest
PATH=\${PATH}:\${JAVA_HOME}/bin
APP_NAME="nexus"
APP_LONG_NAME="Sonatype Nexus"
NEXUS_HOME=/usr/local/nexus
PLATFORM=linux-x86-64
WRAPPER_CMD="\${NEXUS_HOME}/bin/jsw/\${PLATFORM}/wrapper"
WRAPPER_CONF="\${NEXUS_HOME}/bin/jsw/conf/wrapper.conf"
PRIORITY=
PIDDIR="/var/run"
#RUN_AS_USER=nexus
Add Nexus as a Service on Redhat, Fedora, and CentOS

This script has the appropriate chkconfig directives, so all you need to do to add Nexus as a service is run the following commands:

$ cd /etc/init.d
$ chkconfig --add nexus
$ chkconfig --levels 345 nexus on
$ service nexus start
Starting Sonatype Nexus...
$ tail -f /usr/local/nexus/logs/wrapper.log

The second command adds nexus as a service to be started and stopped with the service command and managed by the chkconfig manages the symbolic links in /etc/rc[0-6].d which control the services to be started and stopped when the operating system restarts or transitions between run-levels. The third command adds nexus to run-levels 3, 4, and 5. The service command starts Nexus, and the last command tails the wrapper.log to verify that Nexus has been started successfully. If Nexus has started successfully, you should see a message notifying you that Nexus is listening for HTTP

Add Nexus as a Service on Ubuntu

The process for setting Nexus up as a service on Ubuntu differs slightly from the process used on a Redhat variant. Instead of running chkconfig, you should run the following sequence of commands once you’ve configured the startup script in /etc/init.d

$ cd /etc/init.d
$ update-rc.d nexus defaults
$ service nexus start
Starting Sonatype Nexus...
$ tail -f /usr/local/nexus/logs/wrapper.log

Running Nexus Behind a Proxy

If you installed Nexus as a stand-alone application, Nexus is running on a high-performance servlet container based on Java NIO. From a performance perspective, there is no reason for you not to run Nexus by itself without a proxy. Yet, more often than not, organizations run applications behind a proxy for security concerns and to consolidate multiple disparate applications using tools like mod_rewrite. For this reason, we’ve included some brief instructions for configuration Apache httpd. We assume that you’ve already installed Apache 2, and that you are using a Virtual Host for www.somecompany.com.

Let’s assume that you wanted to host Nexus behind Apache HTTPd at the URL http://www.somecompany.com. To do this, you’ll need to change the context path that Nexus is served from.

  1. named webapp-context-path. Change this value from "/nexus" to "/"

  2. Restart Nexus and Verify that it is available on http://localhost:8081/

  3. Clear the Base URL in Nexus as shown in <xref linkend="fig-nexus-server-config-3" /> under Application Server Settings.

At this point, edit the HTTPd configuration file for the www.somecompany.com virtual host. Include the following to expose Nexus via mod_proxy at http://www.somecompany.com/

ProxyRequests Off
ProxyPreserveHost On

<VirtualHost *:80>
  ServerName www.somecompany.com
  ServerAdmin admin@somecompany.com
  ProxyPass / http://localhost:8081/
  ProxyPassReverse / http://localhost:8081/
  ErrorLog logs/somecompany/nexus/error.log
  CustomLog logs/somecompany/nexus/access.log common
</VirtualHost>

If you just wanted to continue to serve Nexus at the /nexus context path, you would not change the contextPath in in your ProxyPass and ProxyPassReverse

  ProxyPass /nexus/ http://localhost:8081/nexus/
  ProxyPassReverse /nexus/ http://localhost:8081/nexus/

Apache configuration is going to vary based on your own application’s requirements and the way you intend to expose Nexus to the outside world. If you need more details about Apache httpd and mod_proxy, please see http://httpd.apache.org

Installing the Nexus WAR

The Nexus Open Source WAR has been successfully tested in Tomcat, Jetty, and Resin. If you need to run Nexus under Glassfish, please see <xref linkend="install-sect-war-gf" />. To download the Nexus Open Source WAR, go to http://nexus.sonatype.org/using/download.html. Click on the Download Site link and then download the Nexus WAR. Once you have downloaded the Nexus Open Source WAR, you can install it in a servlet container or application server.

The process for installing a WAR in an servlet container or application server is going to vary for each specific application. Often, this installation process is as simple as dropping a WAR file in a special directory and restarting the container. For example, to install the Nexus WAR in Tomcat, drop the your Tomcat instance. Assuming that Tomcat is configured on port 8080 once Tomcat is started, Nexus will be available on http://localhost:8080/nexus-webapp-1.6.0.

If you would like a less verbose URL, copy nexus-webapp-1.6.0.war to a file named nexus.war before copying the distribution to

Note When installing Nexus as a WAR in an application server or servlet container, it automatically creates a sonatype-work directory in ~/sonatype-work. This directory contains all of the necessary configuration and repository storage for Nexus.

Running the Nexus WAR in Glassfish

There is a known logging configuration conflict between the Nexus Open Source WAR and Glassfish. To address this conflict, you will need to modify the log4j.properties file and change a few of the directives that print messages to the console. The log4j.properties file is located in /sonatype-work/conf/log4j.properties. This file is created the first time you attempt to deploy Nexus to Glassfish. To create this file, deploy Nexus to Glassfish. While this initial deployment will fail due to a logging conflict, the act of deploying Nexus to Glassfish will create the working directory in /sonatype-work and the log4j.properties

Edit this log4j.properties file as follows:

  1. On the first line, change "log4j.rootLogger=INFO, console," to "logfilelog4j.rootLogger=INFO, logfile"

  2. Remove the last three lines starting with "log4j.appender.console"

These changes will instruct Log4J not to print messages to the console. Once you make these edits, restart Glassfish.

Installing a Nexus Professional License

To install a Nexus Professional license, click on Licensing in the Enterprise menu. Clicking on Licensing will bring up the panel shown in <xref linkend="fig-installations-licensing" />. To upload your Nexus Professional license, click on Browse…, select the file, and click on Upload.

figs/web/repository-manager_license.png
Figure 6. Nexus Professional Licensing Panel

Once you have selected a license and uploaded it to Nexus, Nexus Professional will display a dialog box with the Nexus Professional End-user License Agreement as shown in <xref linkend="fig-installation-eula" />. If you agree with the terms and conditions, click on "I Agree".

figs/web/installing_license_eula.png
Figure 7. Nexus Professional End-user License Agreement

Once you have agreed to the terms and conditions contained in the End User License Agreement, Nexus Professional will then display a dialog box confirming the installation of a Nexus Professional license as shown in <xref linkend="fig-installation-license-upload-config" />.

figs/web/installing_license_uploaded.png
Figure 8. License Upload Finished Dialog

If you need to move your Nexus Professional license, you can click on the "Uninstall License" button at the bottom of the Licensing Panel. Clicking on this button will show the dialog in <xref linkend="fig-installation-config-uninstall" /> which confirms that you want to uninstall a license.

figs/web/installing_uninstall_license.png
Figure 9. Uninstall License Confirmation Dialog

Clicking Yes in this dialog box will uninstall the license from Nexus Professional and display another dialog which confirms that the license has been successfully uninstalled.

figs/web/installing_uninstall_completed.png
Figure 10. License Uninstall Completed Dialog

Evaluation Expiration

If you have downloaded the Nexus Professional evaluation, you will have thirty days to evaluate the product. After the expiration of this thirty day evaluation period, Nexus Professional will revert back to Nexus Open Source. To reactivate Nexus Professional after the end of your evaluation period, contact a Sonatype sales representative at sales@sonatype.com

Sonatype Nexus Directories

The following sections describe the various directories that are a part of any Nexus installation. When you install Nexus Open Source or Nexus Professional, you are creating two directories: a directory which contains the Nexus runtime and application, and a directory which contains your own configuration and data. When you upgrade to a newer version of Nexus, you replace the Nexus application directory and retain all of your own custom configuration and repository data in sonatype-work/

Sonatype Nexus Work Directory

The Sonatype Work directory is installed as a sibling to the nexus application directory, and the location of this directory can be configured via the plexus.properties file which is described in <xref linkend="sect-installing-conf-dir" />. <xref linkend="fig-installing_work-dir" /> shows the Sonatype Nexus work directory with the conf/

figs/web/installing_work-dir.png
Figure 11. The Sonatype Nexus Work Directory

The Sonatype Nexus work directory contains the following subdirectories:

backup/

If you have configured a scheduled job to backup Nexus configuration, this directory is going to contain a number of ZIP archives that contain snapshots of Nexus configuration. Each ZIP file contains the contents of the conf/ directory. (Automated backups are a feature of Nexus Professional.)

conf/

This directory contains the Nexus configuration. Settings that define the list of Nexus repositories, the logging configuration, the staging and procurement configuration, and the security settings are all captured in this directory.

indexer/

Contains a Nexus index for all repositories and repository groups managed by Nexus. A Nexus index is a Lucene index which is the standard for indexing and searching a Maven repository. Nexus maintains a local index for all repositories, and can also download a Nexus index from remote repositories.

logs/

The nexus.log file that contains information about a running instance of Nexus. This directory also contains archived copies of Nexus log files. Nexus log files are rotated every day. To reclaim disk space, you can delete old log files from the logs/

p2/

If you are using the P2 repository management features of Nexus Professional, this directory contains a local cache of P2 repository artifacts.

proxy/

Stores data about the files contained in a remote repository. Each proxy repository has a subdirectory in the proxy/attributes/ directory and every file that Nexus has interacted with in the remote repository has an XML file which captures such data as the: last requested timestamp, the remote URL for a particular file, the length of the file, and the digests for a particular file among other things. If you need to backup the local cached contents of a proxy repository, you should also back up the contents of the proxy repository’s directory under proxy/attributes/

storage/

Stores artifacts and metadata for Nexus repositories. Each repository is a subdirectory which contains the artifacts in a repository. If the repository is a proxy repository, the storage directory will contain locally cached artifacts from the remote repository. If the repository is a hosted repository, the storage directory will contain all artifacts in the repository. If you need to backup the contents of a repository, you should backup the contents of the storage directory.

template-store/

Contains templates for default repositories. If you examine the XML files in this directory, you will see that they contain default templates for each different type of repository. For example, the repository-default_proxy_release.xml file contains defaults for a Proxy repository with a release policy.

timeline/

Contains an index which Nexus uses to store events and other information to support internal operations. Nexus uses this index to store feeds and history.

trash/

If you have configured scheduled jobs to remove snapshot artifacts or to delete other information from repositories, the deleted data will be stored in this directory. To empty this trash folder, view a list of Nexus repositories, and then click on the Trash icon in the Nexus user interface.

The conf/ directory contains a number of files which allow for configuration and customization of Nexus. All of the files contained in this directory are altered by the Nexus administrative user interface. While you can change the configuration settings contained in these files with a text editor, Sonatype recommends that you modify the contents of these files using the Nexus administrative user interface.

log4j.properties

Contains Log4J configuration, if you need to customize the detail of log messages, the frequency of log file rotation, or if you want to connect your own, custom Log4J appenders, you would alter this configuration file.

lvo-plugin.xml

Contains configuration for the latest version plugin. This XML file contains the location of the properties file which Nexus queries to check for a newer version of Nexus.

nexus.xml

The bulk of the configuration of Nexus is contained in this file. This file maintains a list of repositories, and all server-wide configuration like the SMTP settings, security realms, repository groups, targets, and path mappings.

pgp.xml

Contains PGP key server configuration.

nexus-obr-plugin.properties

Contains configuration for the Nexus OSGi Bundle repository plugin in Nexus Professional.

procurement.xml

Contains configuration for the Nexus Procurement plugin in Nexus Professional.

security.xml

Contains security information about users and roles in Nexus.

staging.xml

Contains configuration for the Nexus Staging plugin in Nexus Professional.

Nexus Configuration Directory

After installing Nexus Professional, you will have a nexus-professional-webapp-${nexus.version}/ directory and a sonatype-work/ directory, and after installing Nexus Open Source, you will have a nexus-webapp-${nexus.version}/ directory and a sonatype-work/ directory. This section details the contents of the conf directory that is shown in <xref linkend="fig-installing_conf-dir" />. This directory contains configuration for the Jetty servlet container. You will only need to modify the files in this directory if you are customizing the configuration of <indexterm> <primary>Plexus <primary>Jetty Jetty servlet container, or the behavior of the scripts that start Nexus.

figs/web/installing_conf-dir.png
Figure 12. Nexus Professional Configuration Directory

The files and folders contained in this directory are:

classworlds.conf

Defines the order in which resources and classes are loaded from the classpath. It is unlikely that even the most advanced Nexus users will ever need to customize the contents of this file.

plexus.properties

This file contains configuration variables which control the behavior of Plexus and the Jetty servlet container. If you are customizing the port and host that Nexus will listen to, you would change the application-port and application-host properties defined in this file. If you wanted to customize the location of the Sonatype work directory, you would modify the value of the nexus-work property in this configuration file.

plexus.xml

Defines the class names and configuration of components which are loaded by Plexus at startup. This file should never be changed as all configurable values have been removed from this file and placed in plexus.properties

jetty.xml

If this file is present in the conf/ directory, it will be used to configure Jetty.

The conf/examples/ directory contains sample Jetty configuration files which can be used to customize the behavior of the Jetty servlet container:

jetty.xml

contains a jetty.xml sample with no customizations. This plexus.properties

jetty-ajp.xml

Contains a jetty.xml sample which will configure Nexus to listen on an AJP port 8009. This configuration can be used if you are proxying your Nexus server with web server which understands the AJP protocol such as Apache httpd with the mod_proxy_ajp module.

jetty-dual-ports-with-ssl.xml

Contains a jetty.xml sample which sample configuration also contains the SSL redirect rule.

jetty-faster-windows.xml

Contains a jetty.xml sample which configures a response buffer size that will address performance issues on Windows 2003 Server, for more information about this fix see <ulink url="http://docs.codehaus.org/display/JETTY/Slow+Win2003">the Jetty Wiki

jetty-header-buffer.xml

Contains a jetty.xml sample which increases the headerBufferSize to 8k from the default of 4k. Documentation about the header buffer size can be found on <ulink url="http://docs.codehaus.org/display/JETTY/Configuring+Connector">the Jetty Wiki

jetty-simple-https-proxy.xml

Contains a jetty.xml sample which should be used if you are proxying a Nexus instance with a web server that is handling SSL. For example, if you were proxying Nexus with Apache httpd server using mod_ssl you would use this configuration to configure the Jetty RewriteHandler

jetty-ssl.xml

Contains a jetty.xml sample which will only serve SSL plexus.properties

The conf/examples/proxy-https/ directory contains two files: apache2.conf and jetty.xml contains sample mod_proxy directives to configure Apache httpd to handle SSL.

Configuring Maven to Use Nexus

Introduction

To use Nexus, you will configure Maven to check Nexus instead of the public repositories. To do this, you’ll need to edit your mirror settings in your <filename>~/.m2/settings.xml file. First, we’re going to demonstrate how to configure Maven to consult your Nexus installation instead of retrieving artifacts directly from the Maven Central repository. After we override the central repository and demonstrate that Nexus is working, we’ll circle back to provide a more sensible set of settings that will cover both releases and snapshots.

Configuring Maven to Use a Single Nexus Group

If you are adopting Nexus for internal development you should configure a single Nexus group which contains both releases and snapshots. To do this, add snapshot repositories to your public group, and add the following mirror configuration to your Maven settings in ~/.m2/settings.xml

Configuring Maven to Use a Single Nexus Group
<settings>
  <mirrors>
    <mirror>
      <!--This sends everything else to /public -->
      <id>nexus</id>
      <mirrorOf>*</mirrorOf>
      <url>http://localhost:8081/nexus/content/groups/public</url>
    </mirror>
  </mirrors>
  <profiles>
    <profile>
      <id>nexus</id>
      <!--Enable snapshots for the built in central repo to direct -->
      <!--all requests to nexus via the mirror -->
      <repositories>
        <repository>
          <id>central</id>
          <url>http://central</url>
          <releases><enabled>true</enabled></releases>
          <snapshots><enabled>true</enabled></snapshots>
        </repository>
      </repositories>
     <pluginRepositories>
        <pluginRepository>
          <id>central</id>
          <url>http://central</url>
          <releases><enabled>true</enabled></releases>
          <snapshots><enabled>true</enabled></snapshots>
        </pluginRepository>
      </pluginRepositories>
    </profile>
  </profiles>
  <activeProfiles>
    <!--make the profile active all the time -->
    <activeProfile>nexus</activeProfile>
  </activeProfiles>
</settings>

In <xref linkend="ex-maven-nexus-simple" /> we have defined a single profile: nexus profile is configured to download from the central repository with a bogus URL. This URL is overridden by the mirror setting in the same settings.xml file to point to the URL of your single Nexus group. The nexus group is then listed as an active profile in the <sgmltag>activeProfiles element.

Adding Custom Repositories for Missing Dependencies

If you’ve configured your Maven settings.xml to list the Nexus public group as a mirror for all repositories, you might encounter projects which are unable to retrieve artifacts from your local Nexus installation. This usually happens because you are trying to build a project which has defined a custom set of repositories and snapshotRepositories in a pom.xml. When you encounter a project which contains a custom repository element in a pom.xml add this repository to Nexus as a new proxy repository and then add the new proxy repository to the public group.

Adding a New Repository

To add a repository, log into Nexus as an Administrator, and click on the Repositories link in the left-hand navigation menu in the Views/Repositories section. Clicking on this link should bring up a window that lists all of the repositories which Nexus knows about. You’ll then want to create a new proxy repository. To do this, click on the Add link that is directly above the list of repositories. When you click the Add button, click the down arrow directly to the right of the word Add, this will show a drop-down which has the options: Hosted Repository, Proxy Repository, Virtual Repository, and Repository Group. Since you are creating a proxy repository, click on Proxy Repository.

figs/web/repository-manager_add-repository-dropdown.png
Figure 13. Creating a New Nexus Proxy Repository

Once you do this, you will see a screen resembling <xref linkend="fig-add-repo" />. Populate the required fields Repository ID and the Repository Name with "caja" and "Google Caja". Set the Repository Policy to "Release", and the Remote Storage Location to http://google-caja.googlecode.com/svn/maven

figs/web/repository-manager_add-repository.png
Figure 14. Adding a Nexus Repository

Once you’ve filled out this screen, click on the Save button. Nexus will then be configured with the caja proxy repository. Do the same thing for the oauth repository. Create a repository with the Repository ID of oauth, with a Release policy, and the Remote Storage Location of http://oauth.googlecode.com/svn/code/maven

Adding a Repository to a Group

Next you will need to add both of these new repositories to the public Nexus Group. To do this, click on the Repositories link in the left-hand navigation menu in the Views/Repositories section. Nexus lists Groups and Repositories in the same list so click on the public group. After clicking on the public group, you should see the Browse and Configuration tabs in the lower half of the Nexus window.

Note If you click on a repository or a group in the Repositories list and you do not see the Configuration tab, this is because your Nexus user does not have administrative privileges. To perform the configuration tasks outlined in this chapter, you will need to be logged in as a user with administrative privileges.

Clicking on the Configuration tab will bring up a screen which looks like <xref linkend="fig-add-to-group" />.

figs/web/repository-manager_add-to-group.png
Figure 15. Adding New Repositories to a Nexus Group

To add the two new repositories to the public Nexus Group, find the repositories in the Available Repositories list on the right, click on the repository you want to add and drag it to the left to the Ordered Group Repositories list. Once the repository is in the Ordered Group Repositories list you can click and drag the repository within that list to alter the order in which a repository will be searched for a matching artifact. Once the Google Caja and Google OAuth project repositories are added to the public Nexus Group, you should be able to build Apache Shindig and watch Maven download the Caja and OAuth artifacts from the respective repositories.

Note Nexus makes use of an interesting Javascript widget library named ExtJS. ExtJS provides for a number of interesting UI widgets that allow for rich interaction like the drag-drop UI for adding repositories to a group and reordering the contents of a group.

In the last few sections, you encountered a situation where you needed to add two custom repositories to a build in order to download two libraries (Google Caja and Google OAuth) which are not available in the Maven Central repository. If you were not using a repository manager, you would have added these repositories to the repository element of your project’s POM, or you would have asked all of your developers to modify ~/.m2/settings.xml to reference two new repositories. Instead, you used the Nexus repository manager to add the two repositories to the public group. If all of the developers are configured to point to the public group in Nexus, you can freely swap in new repositories without asking your developers to change local configuration, and you’ve gained a certain amount of control over which repositories are made available to your development team.

Using Nexus

Introduction

Nexus provides for anonymous access for users who only need to search repositories, browse repositories, and peruse the system feeds. This anonymous access level changes the navigation menu and some of the options available when you right-click on a repository. This read-only access displays a user interface shown in <xref linkend="fig-repoman-anonymous-interface" />.

figs/web/repository-manager_public-interface.png
Figure 16. Nexus Interface for Anonymous Users

Browsing Repositories

One of the most straightforward uses of the Nexus is to browse the structure of a Maven repository. If you click on the Browse Repositories menu item in the Views menu, you should see the following display. The top-half of <xref linkend="fig-nexus-browse-repo" /> shows you a list of groups and repositories along with the type of the repository and the repository status. To browse the artifacts that are stored in a local Nexus instance, click on the Browse Storage tab for a repository as shown in <xref linkend="fig-nexus-browse-repo" />.

figs/web/repository-manager_browse-repositories.png
Figure 17. Browsing a Nexus Repository

When you are browsing a repository, you can right click on any file and download it directly to your browser. This allows you to retrieve specific artifacts manually, or examine a <acronym>POM file in the browser.

Note When browsing a remote repository you might notice that the tree doesn’t contain all of the artifacts in a repository. When you browse a proxy repository, Nexus is displaying the artifacts which have been cached locally from the remote repository. If you don’t see an artifact you expected to see through Nexus, it only means that Nexus has yet to cache the artifact locally. If you have enabled remote repository index downloads, Nexus will return search results that may include artifacts not yet downloaded from the remote repository. <xref linkend="fig-nexus-browse-repo" />, is just an example, and you may or may not have the <varname>doxia-core artifact available in your installation of Nexus.

A Nexus proxy repository acts as a local cache for a remote repository, in addition to downloading and caching artifacts locally, Nexus will also download an index of all the artifacts stored in a particular repository. When searching or browsing for artifacts, it is often more useful to search and browse the repository index. To view the repository index, click on the Browse Index tab for a particular repository to load the interface shown in <xref linkend="fig-nexus-browse-repo-index" />.

figs/web/repository-manager_browse-repository-index.png
Figure 18. Browsing a Nexus Repository Index

As shown in <xref linkend="fig-nexus-browse-repo-index" />, if an artifact has been downloaded from a remote repository and cached in Nexus, the artifact or folder will display a small Nexus logo.

View Artifact Dependencies

Nexus Professional provides you with the ability to browse an artifact’s dependencies. Using the artifact metadata found in an artifact’s POM, Nexus will scan a repository or a repository group and attempt to resolve and display an artifact’s dependencies. To view an artifact’s dependencies, browse the repository storage or the repository index, select an artifact (or an artifact’s POM), and then click on the Maven Dependency tab.

On the Maven Dependency tab, you will see the following form elements:

Repository

When resolving an artifact’s dependencies, Nexus will query an existing repository or repository group. In many cases it will make sense to select the same repository group you are referencing in your Maven Settings. If you encounter any problems during the dependency resolution, you need to make sure that you are referencing a repository or a group which contains these dependencies.

Mode

An artifact’s dependencies can be list as either a tree or a list. When dependencies are displayed in a tree, you can inspect direct dependencies and transitive dependencies. This can come in handy if you are assessing an artifact based on the dependencies it is going to pull into your project’s build. When you list dependencies as a list, Nexus is going to perform the same process used by Maven to collapse a tree of dependencies into a list of dependencies using rules to merge and override dependency versions if there are any overlaps or conflicts.

Once you have selected a repository to resolve against and a mode to display an artifact’s dependencies, click on the Resolve button as shown in <xref linkend="fig-using-dependencies" />. Clicking on this button will start the process of resolving dependencies, depending on the number of artifacts already cached by Nexus, this process can take anywhere from a few seconds to minute. Once the resolution process is finished, you should see the artifact’s dependencies as shown in <xref linkend="fig-using-dependencies" />.

figs/web/using_dependencies.png
Figure 19. View an Artifact’s Dependencies

Once you have resolved an artifact’s dependencies, you can double click on a row in the tree or list of dependencies to navigate to other artifacts within the Nexus interface.

Viewing Artifact Metadata

Nexus Professional gives you the ability to view artifact metadata. When browsing repository storage or a repository index, clicking on an artifact will load the Artifact Information panel. Selecting the Artifact Metadata tab will display the interface shown in <xref linkend="fig-using-viewing-metadata" />.

figs/web/meta_existing-meta-value.png
Figure 20. Viewing Artifact Metadata

Artifact metadata consists of a key, a value, and a namespace. Existing metadata from an artifact’s POM is given a urn:maven namespace, and custom attributes are stored under the urn:nexus/user namespace.

Editing Artifact Metadata

Nexus Professional gives you the ability to add custom attributes to artifact metadata. To add a custom attribute, click on an artifact in Nexus, and select the Artifact Metadata tab. On the Artifact Metadata tab, click on the Add… button and a new row will be inserted into the list of attributes. Supply a key and value and click the Save button to update an artifact’s metadata. <xref linkend="fig-using-editing-metadata" /> shows the Artifact Metadata panel with two custom attributes: "approvedBy" and "approved".

figs/web/meta_setting-meta-value.png
Figure 21. Editing Artifact Metadata

Browsing Groups

Nexus contains ordered groups of repositories which allow you to expose a series of repositories through a single URL. More often than not, an organization is going to point Maven at the two default Nexus groups: Public Repositories and Public Snapshot Repositories. Most end-users of Nexus are not going to know what artifacts are being served from what specific repository, and they are going to want to be able to browse the Public Repository. To support this use case, Maven allows you to browse the contents of a Nexus Group as if it were a single merged repository with a tree structure. <xref linkend="fig-nexus-browse-group" />, shows the browsing storage interface for a Nexus Group. There is no difference to the user experience of browsing a Nexus Group vs. browsing a Nexus Repository.

figs/web/repository-manager_browse-group.png
Figure 22. Browsing a Nexus Group

When browsing a Nexus group’s storage, you are browsing the underlying storage for all of the repositories which are contained in a group. If a Nexus group contains proxy repositories, the Browse Storage tab will show all of the artifacts in the Nexus group that have been download from the remote repositories. To browse and search all artifacts available in a Nexus group, click on the Browse Index tab to load the interface shown in <xref linkend="fig-nexus-browse-group-index" />.

figs/web/repository-manager_browse-group-index.png
Figure 23. Browsing a Nexus Group Index

Searching for Artifacts

In the left-hand navigation area, there is an Artifact Search text field next to a magnifying glass. To search for an artifact by groupId or artifactId, type in some text and click the magnifying glass. Typing in the search term "guice" and clicking the magnifying glass should yield a search result similar to <xref linkend="fig-nexus-search" />.

figs/web/search-results.png
Figure 24. Results of an Artifact Search for "guice"

Once you’ve located the artifact you were looking for you can click on the pom link to download the POM or the artifact link to download the artifact.

  • Look at the Version column in the search results. In this version of the search interface, we decided to list the most recent version. If you need to view a different version, click on "Show All Versions". Clicking on "Show All Versions" will drill down into the list of available versions.

  • Look at the Download column in the search results. This Download column contains direct download links for the most recent version of the artifact. To download a matching artifact, just click on a link in this column.

  • Select a search result, and you will see the artifact in the Repository Tree in the lower left-hand quadrant of this interface. This is helpful to give you context for an artifact. An artifact could be present in more than one repository. If this is the case, click on the value next to "Viewing Repository" to switch between multiple matching repositories.

  • In the lower right-hand quadrant of the interface, you will see a number of tabs which show information about the selected search result:

    • Maven Information: This contains basic identifiers and a snippet of XML you can use to add this artifact as a project dependency.

    • Archive Browser (Nexus Professional): This gives you a way to explore the contents of an archive in the repository. You can view the files and folders contained in a matching search result.

    • Artifact Information: This tab contains timestampes, file size, checksum values, and a list of repositories containing a given artifact.

    • Artifact Metadata (Nexus Professional): This tab shows all of the built-in and custom metadata associated with an artifact.

In addition to searching by a groupId or an artifactId, Nexus has a feature which allows you to search for an artifact by a checksum.

Warning Let me guess? You installed Nexus, ran to the search box, typed in the name of a group or an artifact, pressed search, and saw absolutely nothing. No results. Nexus isn’t going to retrieve the remote repository indexes by default, you need to activate downloading of remote indexes for the three proxy repositories that Nexus ships with. Without these indexes, Nexus has nothing to search. Find instructions for activating index downloads in <xref linkend="config-sect-manage-repo" />.

Nexus OpenSearch Integration

OpenSearch a standard which facilitates searching directly from your browser’s search box. If you are using Internet Explorer 7+ or Firefox 2+ you can add any Nexus instance as an OpenSearch provider. Then you can just type in a search term into your browser’s search field and quickly search for Maven artifacts. To configure OpenSearch, load Nexus in a browser and then click on the dropdown next to the search tool that is embedded in your browser. <xref linkend="fig-using-opensearch-configure" /> shows the Add Nexus option that is present in Firefox’s OpenSearch provider dropdown.

figs/web/using_opensearch-config.png
Figure 25. Configuring Nexus as an OpenSearch Provider

Once you have added Nexus to the list of OpenSearch providers, click on the dropdown next to the search term and select Nexus (localhost) from the list of OpenSearch providers. Type in a groupId, artifactId, or portion of a Maven identifier and press enter. Your opensearch-friendly web browser will then take you to the search results page of Nexus displaying all the artifacts that match your search term.

figs/web/using_opensearch-search.png
Figure 26. OpenSearch Search Results in Nexus

Once, you have configured your browser to use Nexus as an OpenSearch provider, searching for a Maven artifact is as simple as typing in a groupId or artifactId, selecting Nexus from the dropdown shown in <xref linkend="fig-using-permanent-opensearch-option" />, and performing a search.

figs/web/using_opensearch-permanent.png
Figure 27. Nexus Available as an Option in the Firefox OpenSearch Provider List

Searching Artifact Metadata

Nexus Professional provides you with the ability to configure custom artifact metadata and search for artifacts with specific metadata. To search for artifacts using metadata, click on the Advanced Search link directly below the search field in the Nexus application menu to open the Search panel. Once in the search panel, click on the Keyword Search and click on Metadata Search in the search type dropdown as shown in <xref linkend="fig-using-search-metadata" />.

figs/web/meta_search-selection.png
Figure 28. Searching Artifact Metadata

Once you select the Metadata Search you will see two search fields and an operator dropdown. The two search fields are the key and value of the metadata you are searching for. The key corresponds to the key of the metadata you are searching for, and the value contains the value or value range you are searching for. The operator dropdown can be set to Equals, Matches, Bounded, or Not Equal.

figs/web/meta_search-function.png
Figure 29. Metadata Search Results for Custom Metadata

Once you locate a matching artfiact in the Metadata Search interface, click on the artifact and then select the Artifact Metadata to examine an artifacts metadata as shown in <xref linkend="fig-using-search-metadata-results" />.

figs/web/meta_search-result-0.png
Figure 30. Metadata Search Results for Custom Metadata

Uploading Artifacts

When your build makes use of proprietary or custom dependencies which are not available from public repositories, you will often need to find a way to make them available to developers in a custom Maven repository. Nexus ships with a preconfigured 3rd Party repository that was designed to hold 3rd Party dependencies which are used in your builds. To upload artifacts to a repository, select a hosted repository in the Repositories panel and then click on the Artifact Upload tab. Clicking on the Artifact Upload tab will display the tab shown in <xref linkend="fig-using-artifact-upload" />.

figs/web/using_artifact-upload.png
Figure 31. Artifact Upload Form

To upload an artifact, click on Select Artifact(s) for Upload… and select one or more artifacts from the filesystem to upload. Once you have selected an artifact, you can modify the classifier and the extension before clicking on the Add Artifact button. Once you have clicked on the Add Artifact button, you can then configure the source of the Group, Artifact, Version (GAV) parameters. If the artifact you are uploading is a JAR file that was created by Maven it will already have POM information embedded in it. If you are uploading a JAR from a vendor you will likely need to set the Group Identifier, Artifact Identifier, and Version manually. To do this, select GAV Parameters from the GAV Definition dropdown at the top of this form. Selecting GAV Parameters will expose a set of form fields which will let you set the Group, Artifact, Version, and Packaging of the artifacts being uploaded. If you would prefer to set the Group, Artifact, and Version from a POM file associated with the uploaded artifact, select From POM in the GAV Definition dropdown. Selecting From POM in this dropdown will expose a button labeled "Select POM to Upload". Once a POM file has been selected for upload, the name of the POM file will be displayed in the form field below this button.

The Artifact Upload panel supports multiple artifacts with the same Group, Artifact, and Version identifiers. For example, if you need to upload multiple artifacts with different classifiers, you may do so by clicking on Select Artifact(s) for Upload and Add Artifact multiple times.

Browsing System Feeds

Nexus provides feeds that capture system events, you can browse these feeds by clicking on System Feeds under the View menu. Clicking on System Feeds will show the panel in <xref linkend="fig-repoman-system-feeds" />. You can use these simple interface to browse the most recent reports of artifact deployments, cached artifacts, broken artifacts, and storage changes that have occurred in Nexus.

figs/web/repository-manager_system-feed.png
Figure 32. Browsing Nexus System Feeds

These feeds can come in handy if you are working at a large organization with multiple development teams deploying to the same instance of Nexus. If such an arrangement, all developers in an organization can subscribe to the RSS feeds for New Deployed Artifacts as a way to ensure that everyone is aware when a new release has been pushed to Nexus. Exposing these system events as RSS feeds also opens to the door to other, more creative uses of this information, such as connecting Nexus to external automated testing systems. To access the RSS feeds for a specific feed, select the feed in the System Feeds view panel and then click on the Subscribe button. Nexus will then load the RSS feed in your browse and you can subscribe to the feed in your favorite RSS

There are six system feeds available in the System Feeds view, and each has a URL which resembles the following URL

http://localhost:8081/nexus/service/local/feeds/recentlyChangedFiles

Where recentChanges would be replaced with the identifier of the feed you were attempting to read. Available system feeds include:

Table 1. Available System Feeds
Feed Identifier Description

systemRepositoryStatusChanges

Automatic or User-initiated status changes (out-of-service and blocked proxies)

systemChanges

authcAuthz

Authentication and Authorization Events

brokenArtifacts

Broken Artifacts (Checksum mismatch, missing checksums, invalid POMs)

brokenFiles

Broken Files (Checksum errors.)

errorWarning

Errors, warnings, and exceptions from Nexus

recentlyCachedOrDeployedArtifacts

New artifacts in all repositories (cached or deployed)

recentlyCachedOrDeployedFiles

New files in all repositories (cached or deployed)

recentlyCachedArtifacts

New cached artifacts in all repositories

recentlyCachedFiles

New cached files in all repositories

recentlyDeployedArtifacts

New deployed artifacts in all repositories

recentlyDeployedFiles

New deployed files in all repositories

recentlyChangedArtifacts

Changed artifacts in all repositories

recentlyChangedFiles

Changed files in all repositories

Log Files and Configuration

The Logs and Config Files link is only visible to Administrative users under the Views menu. Click on this option brings up the dialog shown in <xref linkend="fig-nexus-logs" />. From this screen you can view the following log and configuration files by clicking on the drop down selection next to the Download button.

nexus.log

Think of this as the general application log for Nexus. Unless you are an administrative user, you might not have must interest in the information in this log. If you are trying to debug an error, or if you have uncovered a bug in Nexus, you’ll use this log viewer to diagnose problems with Nexus.

nexus.xml

This XML file contains most of the configuration data for your instance of Nexus. It is stored in

log4j.properties

This file controls the logging facility of Nexus using the standard Log4J property file syntax. To edit the format or level of the Log4J logging, click on Log under the Administration menu. For more information about configuring the Nexus Log, see <xref linkend="configuring-sect-log" />.

security.xml

This XML file contains the configuration for the XmlAuthenticatingRealm and the XmlAuthorizingRealm. It contains built-in user definitions and any externally mapped users that are mapped to Nexus roles.

figs/web/repository-manager_log-file.png
Figure 33. Browsing Nexus Logs and Configuration

If you are running Nexus Professional, you should see a few more configuration files in this directory which will correspond to the Procurement and Staging suites. The configuration files specific to Nexus Professional are:

procurement.xml

This file contains the configuration for the Nexus Procurement Suite as described in <xref linkend="procure" />.

staging.xml

This file contains the configuration for the Staging Suite as described in <xref linkend="staging" />.

In <xref linkend="fig-nexus-logs" /> there is a "tail" checkbox. If this box is checked, then Nexus will always show you the end of a log file. This can come in handy if you want to see a continuously updated log file. When this tail box is checked, a dropdown at the bottom of the panel allows you to set the update frequency. The contents of this dropdown are shown in <xref linkend="fig-using-update-freq" />. If an update interval is selected, Nexus will periodically refresh the selected log file.

figs/web/using_tail-frequency.png
Figure 34. Selecting the Update Frequency when Tailing a Log File

Changing Your Password

If you have the appropriate security privilege, you will see an option to change your password in the left-hand side of the browser. To change your password, click on change password, supply your current password, and choose a new password. When you click on Change Password, your Nexus password will be changed.

figs/web/repository-manager_change-password.png
Figure 35. Changing Your Nexus Password

Filing a Problem Report

If you encounter a problem with Nexus, you can use the Nexus UI to report a bug or file an issue against the Nexus project in Sonatype’s JIRA instance. To file a problem report, you will first need to sign up for an account on http://issues.sonatype.org. In Nexus 1.6, you can click on "File Issue" in the Nexus menu, supply your Sonatype JIRA credentials, and file a problem report. Supply your JIRA username and password along with a short title and a description as shown in the following figure. When you file a Nexus problem report, Nexus will create a new issue in JIRA and attach your configuration and logs to the newly filed issue.

figs/web/configuring-generate-report.png
Figure 36. Generating a Nexus Problem Report

Configuring Nexus

Configuring Nexus

Many of the configuration screens shown in this section are only available to administrative users. Nexus allows the admin user to customize the list of repositories, create repository groups, customize server settings, and create routes or "rules" that Maven will use to include or exclude artifacts from a repository.

Customizing Server Configuration

In a production installation of Nexus, you’ll probably want to customize the administrative password to something other than "admin123", and you might want to override the default directories that Nexus uses to store repository data. To do this, log in as the administrative user and click on Server under Configuration in the left-hand navigation menu. The server configuration screen is shown in <xref linkend="fig-nexus-server-config" /> and <xref linkend="fig-nexus-server-config-2" />.

figs/web/repository-manager_server-settings.png
Figure 37. Nexus Server Configuration (File, SMTP, and HTTP Config)
figs/web/repository-manager_server-settings-2.png
Figure 38. Nexus Server Configuration (Security Settings, Anonymous Access)
figs/web/repository-manager_server-settings-3.png
Figure 39. Nexus Server Configuration (App Server and HTTP Proxy Config)
figs/web/configuring_pgp-keyserver.png
Figure 40. Configuring PGP Keyserver Preferences

This screen allows you to change:

SMTP Settings

Nexus sends email to users who need to recover usernames and password. To do this, you’ll need to configure the SMTP server settings in this dialog. This section of the form takes an SMTP Host and Port as well as other parameters relating to SMTP authentication and encryption. You can also change the From: header of an email from Nexus.

User Agent

This is the identifier which Nexus uses when it is making an HTTP request. You may want to change this if Nexus needs to use an HTTP Proxy, and the Proxy will only work if the User Agent is set to a specific value.

Additional URL

This is a list of extra parameters to place on a GET request to a remote repository. You could use this to add identifying information to requests.

Request Timeout

The amount of time Nexus will wait for a request to succeed when interacting with an external, remote repository.

Request Retry Attempts

The number of times Nexus will retry a failed HTTP

Security Settings

You can choose to enable or disable security, enable or disable anonymous access, and set the username and password for anonymous access. If you choose to enable security, you are telling Nexus to enforce role-based access control to enforce read and write access to repositories.

The anonymous username and password is used to integrate with other realms that may need a special username for anonymous access. In other words, the username and password here is what we attempt to authorize when someone makes an anonymous request. You would change the anonymous username to “guest” if you wanted to integrate Nexus with Microsoft’s Active Directory.

Application Server Settings

This section allows you to change the Base URL for your Nexus installation. It is used when generating links in emails and RSS feeds. The Sonatype Nexus repository is available on http://respository.sonatype.org, and it makes use of this Base URL field to ensure that links in emails and RSS feeds point to the correct URL. If you are hosting Nexus behind a proxy server and you want to make sure that Nexus always uses the specified Base URL, check the "Force Base URL" checkbox. If the Force Base URL is not checked, Nexus will craft URLs in HTTP responses based on the request URL, but it will use the Base URL when it is generating emails.

HTTP Proxy Settings

There are a number of HTTP Proxy settings for Nexus installations which need to be configured to use an HTTP Proxy. You can specify a host, port, and a number of authentication options which might be required by your proxy server.

PGP Key Server Information

Nexus Professional uses a PGP Key Server to retrieve PGP keys when validating artifact signatures. To add a new Key Server URL, enter the URL in the Key Server URL field and click on the Add button. To remove a Key Server URL, click on the URL you wish to remove from the list and click on the Remove button. Key Servers are consulted in the order that they are listed in the Key Server URLs list, to reorder your Key Server URLs, click and drag a URL in the Key Server URLs list.

Configuring Automated Error Reporting Settings

Nexus can be configured to automatically file exception and error reports with the Nexus project in the Sonatype issue tracker. Activating this setting in your own Nexus installation helps to improve Nexus as the development team will receive automatic error reports if your Nexus instance experiences an error or a failure. The Nexus Server configuration’s Automated Error Reporting Settings section is shown in <xref linkend="fig-configuring-automated-error" />. This section accepts a JIRA username and password, and allows you to configure Nexus to use the default HTTP Proxy Settings when Nexus attempts to file an error report with the Sonatype issue tracker.

figs/web/configuring_automated-error.png
Figure 41. Configuring the Automated Error Reporting

To sign up for an account on the Sonatype JIRA instance, go to http://issues.sonatype.org. Once you see the website shown in <xref linkend="fig-configuring-sonatype-jira" />, click on the "Signup" link below the Login form.

figs/web/configuring_automated-error-jira-home.png
Figure 42. Sonatype Issue Tracker

Fill out the signup form shown in <xref linkend="fig-configuring-sonatype-jira-signup" />, and choose a username and password. This is the username and password you should use in the Automated Error Reporting Settings section of the Server configuration shown in <xref linkend="fig-configuring-automated-error" />.

figs/web/configuring_automated-error-jira-signup.png
Figure 43. Signing Up for a Sonatype Issue Tracker Account

New Version Notification

Nexus can notify you of new versions of Nexus via the Nexus interface. To enable this feature, check the Enable checkbox in the New Version Notification section of the Nexus server settings as shown in <xref linkend="fig-configuring-new-version" />.

figs/web/configuring_new-version.png
Figure 44. New Version Notification Settings

Managing Repositories

To manage Nexus repositories, log in as the administrative user and click on Repositories in the Views/Repositories menu in the left-hand navigation menu. If you are logged into Nexus as a user with administrative privileges, you will see Configuration and Mirrors tabs in the lower portion of the Nexus window.

Nexus provides for three different kinds of repositories:

Proxy Repository

A proxy repository is a proxy of a remote repository. By default, Nexus ships with the following configured proxy repositories:

Apache Snapshots

This repository contains snapshot releases from the Apache Software Foundation http://people.apache.org/repo/m2-snapshot-repository

Codehaus Snapshots

This repository contains snapshot released from Codehaus http://snapshots.repository.codehaus.org/

Maven Central Repository

This is the central repository (for releases). http://repo1.maven.org/maven2/

Hosted Repository

A hosted repository is a repository which is hosted by Nexus. Maven ships with the following configured hosted repositories:

3rd Party

This hosted repository should be used for third-party dependencies not available in the public Maven repositories. Examples of these dependencies could be commercial, proprietary libraries such as an Oracle JDBC driver that may be referenced by your organization.

Releases

This hosted repository is where your organization will publish internal releases.

Snapshots

This hosted repository is where your organization will publish internal snapshots.

Virtual Repository

This serves as an adapter to and from different types of repositories. Currently Nexus supports conversion to and from Maven 1 repositories and Maven 2 repositories.

figs/web/repository-manager_repository-config.png
Figure 45. Repository Configuration Screen for a Proxy Repository
figs/web/repository-manager_repository-config-2.png
Figure 46. Repository Configuration Screen for a Proxy Repository
figs/web/repository-manager_repository-config-3.png
Figure 47. Proxy Configuration Access Settings for a Hosted Repository

<xref linkend="fig-repo-config" /> shows the Repository configuration screen for a Proxy repository in Nexus. From this screen, you can manage the settings for proxying an external repository. From this screen, you can configure:

Repository ID

The repository ID is the identifier which will be used in the Nexus URL. For example, the central proxy repository has an ID of "central", this means that maven can access the repository directly at http://localhost:8081/nexus/content/repositories/central. The Repository ID must be unique in a given Nexus installation. ID is required.

Repository Name

The display name for a repository. Name is required.

Repository Type

The type of repository (proxy, hosted, or virtual). You can’t change the type of a repository, it is selected when you create a repository.

Repository Policy

If a proxy repository has a policy of release than it will only access released versions from the remote repository. If a proxy repository has a policy of snapshot, it will download snapshots from the remote repository.

Default Storage Location

Not editable, shown for reference. This is the default storage location for the local cached contents of the repository.

Override Storage Location

You can choose to override the storage location for a specific repository. You would do this if you were concerned about storage and wanted to put the contents of a specific repository (such as central) in a different location.

Remote Repository Access

This section tells Nexus where to look for and how to interact with the remote Maven repository being proxied.

Remote Storage Location

This is the URL of the remote Maven repository.

Download Remote Indexes (Not shown in figure)

This field controls the downloading of the remote indexes. Currently only central has an index at http://repo1.maven.org/maven2/.index.

If enabled, Nexus will download the index and use that for its searches as well as serve that up to any clients which ask for the index (like m2eclipse). The default for new proxy repositories is enabled, but all of the default repositories included in Nexus have this option disabled. To change this setting for one of the proxy repositories that ship with Nexus, change the option, save the repository, and then re-index the repository. Once this is done, artifact search will return every artifact available on the Maven Central repository.

Auto blocking active

If Auto blocking active is set to true, Nexus will automatically block a proxy repository if the remote repository becomes unavailable. While a proxy repository is blocked, artifacts will still be served to clients from a local cache, but Nexus will not attempt to locate an artifact in a remote repository. Nexus will periodically retest the remote repository and unblock the repository once it becomes available.

File content validation (Not shown in figure)

If set to true, Nexus will perform a lightweight check on the content of downloaded files. This will prevent invalid content to be stored and proxied by Nexus, which otherwise can happen in cases where the remote repository (or some proxy between Nexus and the remote repository) for example returns an html page instead of the requested file.

Checksum Policy

Sets the checksum policy for a remote repository. This option is set to Warn by default. The possible values of this setting are:

  • Ignore - Ignore the checksums entirely

  • Warn - Print a warning in the log if a checksum is not correct

  • StrictIfExists - Refuse to cache an artifact if the calculated checksum is inconsistent with a checksum in the repository. Only perform this check if the checksum file is present.

  • Strict - Refuse to cache an artifact if the calculated checksum is inconsistent or if there is no checksum for an artifact.

Authentication

This section allows you to set a Username, Password, Private Key, Key Passphrase, NT LAN Host, and NT Lan Manager Domain for a remote repository.

Access Settings

This section configures access settings for a repository.

Deployment Policy

This setting controls how a Hosted repository allows or disallows artifact deployment. If this policy is set to "Read Only", no deployment is allowed. If this policy is set to "Disable Redeploy", a client can only deploy a particular artifact once and any attempt to redeploy an artifact will result in an error. If this policy is set to "Allow Redeploy", clients can deploy artifacts to this repository and overwrite the same artifact in subsequent deployments. This option is visible for Hosted repositories as shown in <xref linkend="fig-repo-config-hosted" />.

Allow File Browsing

When set to true, users can browse the contents of the repository with a web browser.

Include in Search

When set to true, this repository is search when you perform an Artifact Search in Nexus. If this setting is false, the contents of the repository are excluded from a search.

Publish URL

If this property is set to false, the repository will not be published on a URL, and you will not be able to access this repository remotely. You would set this configuration property to false if you want to prevent clients for connecting to this repository directly.

Expiration Settings

Nexus maintains a local cache of artifacts and metadata, you can configure expiration parameters for a proxy repository. The expiration settings are:

Not Found Cache TTL

If Nexus fails to locate an artifact, it will cache this result for a given number of minutes. In other words, if Nexus can’t find an artifact in a remote repository, it will not repeated attempt to resolve this artifact until the Not Found Cache TTL time has been exceeded. The default for this setting is 1440 minutes (or 24 hours).

Artifact Max Age

Tells Nexus when that maximum age of an artifact is before it retrieves a new version from the remote repository. The default for this setting is -1 for a repository with a Release policy and 1440 for a repository with Snapshot policy.

Metadata Max Age

Nexus retrieves metadata from the remote repository. It will only retrieve updates to metadata after the Metadata Max Age has been exceeded. The default value for this setting is 1440 minutes (or 24 hours).

HTTP Request Settings

This section lets you change the properties of the HTTP request to the remote repository. In this section you can configure the User Agent of the request, add parameters to a request, and set the timeout and retry behavior. This section refers to the HTTP request made from Nexus to the remote Maven repository being proxied.

HTTP Proxy Settings

This section lets you configure the HTTP Proxy for the request from Nexus to the remote repository. You can configure a proxy host and port plus an authentication settings you need tell Nexus to use an HTTP Proxy for all requests to a remote repository.

Selecting Mirrors for Proxy Repositories

Nexus also allows you to select which mirrors Nexus will consult for a particular Proxy repository. Clicking on the Mirrors tab will show the figure shown in <xref linkend="fig-configuring-mirror-config" />.

figs/web/repository-manager_config-mirrors.png
Figure 48. Configuring Mirrors for Proxy Repositories

To configure a mirror repository, click on the Mirror URL dropdown and select a mirror for the Proxy repository. Click the Add button, and Nexus will then be configured to download artifacts from the selected mirror. Nexus will always download checksums and metadata from the original (or Canonical) URL for a proxy repository. For example, if Nexus is going to download an artifact, it will retrieve the MD5 checksum from the original Maven Central repository and then retrieve the artifact from the selected mirror.

Adding a Mirror Entry for a Hosted Repository

If you are logged in as a user with Administrative privilege, there will be a Mirrors tab available when you are viewing a Hosted repository, clicking on this Mirrors tab will show the form shown in <xref linkend="fig-configuring-mirrors-hosted" />. This tab contains a list of mirror URLs for this hosted repository. If there are other sites which mirror the contents of this hosted repository, this tab allows you to populate the repository mirror metadata with those URLs.

figs/web/configuring_hosted-mirrors.png
Figure 49. Configuring Mirrors for a Hosted Repository

This repository mirror metadata can then be consumed by other systems that interact with your hosted repository. For example, if you have a release repository which is used by your customers or by the general public, if one of people consuming your Hosted repository is also running a Nexus, they can configure a Proxy repository that targets your Hosted repository and they can use the mirror metadata to configure their instance of Nexus to consume artifacts from mirrors of your Hosted repository.

Viewing Repository Summary Panel

The Repository Summary panel can be loaded by selecting a Hosted, Proxy, or Virtual repository and then clicking on the Summary tab. When viewing the Summary tab of a Hosted repository, as shown in <xref linkend="fig-configuring-summary-hosted" />, you will also see the Distribution Management settings which can be used to configure Maven to publish artifacts to a Hosted repository.

figs/web/repository-manager_summary-hosted.png
Figure 50. Repository Summary Panel for a Hosted Repository

The Repository Summary panel for a Proxy repository, as shown in <xref linkend="fig-configuring-summary-proxy" />, contains all of the repository identifiers and configuration in addition to the size of the local storage for the proxy repository and the URL of the remote repository.

figs/web/repository-manager_summary-proxy.png
Figure 51. Repository Summary Panel for a Proxy Repository

The Repository Summary panel for a Virtual repository, as shown in <xref linkend="fig-configuring-summary-virtual" />, displays repository identifiers and the size of the Virtual repository on disk.

figs/web/repository-manager_summary-virtual.png
Figure 52. Repository Summary Panel for a Virtual Repository

Auto Block/Unblock of Remote Repositories

What happens when Nexus is unable to reach a remote repository? If you’ve defined a proxy repository, and the remote repository is unavailable Nexus will now automatically block the remote repository. Once a repository has been auto-blocked, Nexus will then periodically retest the remote repository and unblock the repository once it becomes available. You can control this behavior by changing the Auto-blocking Active setting under the Remote Repository Access section of the proxy repository configuration as shown in the following figure:

figs/web/configuring_auto-block.png
Figure 53. Configuring Remote Repository Auto Block/Unblock

Managing Groups

Groups are a powerful feature of Nexus, they allow you to combine multiple repositories and other repository groups in a single URL. Nexus ships with two groups: public and public-snapshots. The public group combines the three hosted repositories: 3rd Party, Releases, and Snapshots with the Maven Central repository. The public-snapshots repository combines the Apache Snapshots and Codehaus Snapshots repositories.

In <xref linkend="maven-sect-single-group" /> we configured Maven via the <filename>settings.xml to look for artifacts in the public group managed by Nexus. <xref linkend="fig-group-config" /> shows the group configuration screen in Nexus, in this figure you can see the contents of the public

figs/web/repository-manager_group-config.png
Figure 54. Group Configuration Screen in Nexus

Note that the order of the repositories listed in Order Group Repositories is important. When Nexus searches for an artifact in a group it will return the first match. To reorder a repository in this list, click and the drag the repositories and groups in the Ordered Group Repositories selection list.

The order of repositories or other groups in a group can be used to influence the effective metadata that will be retrieved by Maven from a Nexus Repository Group. We recommend placing release repositories higher in the list than snapshot repositories so that LATEST and RELEASE versions are merged appropriately. We also recommend placing repositories with a higher probability of matching the majority of artifacts higher in this list. If most of your artifacts are going to be retrieved from the Maven Central Repository, putting Central higher in this list than a smaller, more focused repository is going to be better for performance as Nexus is not going to interrogate the smaller remote repository for as many missing artifacts.

Managing Routes

Nexus Routes are like filters you can apply to Nexus Groups, they allow you to configure Nexus to include or exclude repositories from a particular artifact search when Nexus is trying to locate an artifact in a Nexus Group. There are a number of different scenarios in which you might configure a route in Nexus, the most common is when you want to make sure that you are retrieving artifacts in a particular group ID from a particular repository. This is especially useful when you want to make sure that you are trying to retrieve your own organization’s artifacts from the hosted Release and Snapshot repositories. Nexus Routes are applicable when you are trying to resolve an artifact from a Nexus Group; using Routes allow you to modify the repositories Nexus will consult when it tries to resolve an artifact from a group of repositories.

figs/web/repository-manager_route-config.png
Figure 55. Routes Configuration Screen in Nexus

<xref linkend="fig-route-config" /> shows the Route Configuration screen. Clicking on a route will bring up a screen which will allow you to configure the properties of a route. The configuration options available for a route are:

URL Pattern

This is the pattern which Nexus will use to match a request to Nexus. If the regular expression in this pattern is matched, Nexus will either include or exclude the listed repositories from a particular artifact query. In <xref linkend="fig-route-config" /> the two patterns are:

"./(com|org)/somecompany/."

This pattern would match all of the paths which included either "/com/somecompany/" or "/org/somecompany". The expression in the parenthesis matches either com or org, and the ".*" matches one or more characters. You would use a route like this to match your own organization’s artifacts and map these requests to the hosted Nexus Releases and Snapshots repositories.

"./org/some-oss/."

This pattern is used in an exclusive route. It matches every path that contains "/org/some-oss/". This particular exclusive route excludes the local hosted Releases and Snapshots directory for all artifacts which match this path. When Nexus tries to resolve artifacts that match this path, it will exclude the Releases and Snapshots repositories.

Rule Type

Rule Type can be either "inclusive" or "exclusive". An inclusive rule type defines the set of repositories which should be searched for artifacts when the URL pattern has been matched. An exclusive rule type defines repositories which should not be searched for a particular artifact.

Ordered Route Repositories

This is an ordered list of repositories which Nexus will search to locate a particular artifact. Nexus searches top to bottom; if it’s looking for an artifact, it will return the first match. When Nexus is looking for metadata, all repositories in a group are checked and the results are merged. The merging is applied giving preference to the earlier repositories. This is relevant when a project is looking for a LATEST or a RELEASE version. Within a Nexus Group, you should define the release repositories before the snapshot repositories, otherwise LATEST may incorrectly resolve to a snapshot version.

In this figure you can see the two dummy Routes that Nexus has as default routes.

The first route is an inclusive route, it is provided as an example of a custom route an organization might use to make sure that internally generated artifacts are resolved from the Releases and Snapshots repositories. If your organization’s group IDs all start with com.somecompany, and if you deploy internally generated artifacts to the Releases and Snapshots repositories, this Route will make sure that Nexus doesn’t waste time trying to resolve these artifacts from public Maven repositories like the Maven Central Repository or the Apache Snapshots repository.

The second dummy route is an exclusive route. This route excludes the Releases and Snapshots repositories when the request path contains "/org/some-oss". This example might make more sense if we replaced "some-oss" with "apache" or "codehaus". If the pattern was "/org/apache", this rule is telling Nexus to exclude the internal Releases and Snapshots repositories when it is trying to resolve these dependencies. In other words, don’t bother looking for an Apache dependency in your organization’s internal repositories.

What if there is a conflict between two routes? Nexus will process inclusive routes before it will process the exclusive routes. Remember that Nexus Routes only affect Nexus' resolution of artifacts when it is searching a Group. When Nexus starts to resolve an artifact from a Nexus Group it will start with the list of repositories in a group. If there are matching inclusive routes, Nexus will then take the intersection of the repositories in the Group and the repositories in the inclusive Nexus Route. The order as defined in the Nexus Group will not be affected by the Inclusive routes. Nexus will then take the result of applying the inclusive routes and apply the exclusive routes to this new group. The resulting list is then searched for a matching artifact. One straightforward use of routes is to create a route that excludes the

Maven Central repository from all searches for your own organization’s hosted artifacts. If you are deploying your own artifacts to Nexus under a groupId of org.mycompany, and if you are not deploying these artifacts to a public repository, you can create a rule that tells Nexus not to interrogate Central for your own organization’s artifacts. This will improve performance because Nexus will not need to communicate with a remote repository when it serves your own organization’s artifacts. In addition to the performance benefits, excluding Central from searches for your own artifacts will reduce needless queries to the public repositories.

To summarize, there are creative possibilities with Routes that the designers of Nexus may not have anticipated, but we advise you to proceed with caution if you start relying on conflicting or overlapping Routes. Use Routes sparingly, and use course URL patterns, as Nexus evolves there will be more features which allow for more fine grained rules to allow you to prohibit requests for specific artifacts and specific versions of artifacts. Remember that routes are only applied to Nexus Groups, routes are not used when an artifact is requested from a specific repository.

Managing Scheduled Tasks

Nexus allows you to schedule tasks that will be applied to all repositories or to specific repositories on a configurable schedule. You can create the following kinds of scheduled tasks:

Download Indexes

This scheduled task will cause Nexus to download indexes from remote repositories.

Empty Trash

The Evict and Purge actions do not delete data from the Nexus working directory. They simply move data to be cleared or evicted to a trash directory under the Nexus work directory. This service deletes the data in this trash directory.

Evict Unused Proxied Items From Repository Caches

Use it or lose it. This scheduled task tells Nexus to get rid of all proxied items which haven’t been "used" (referenced or retrieved by a client). This can be a good job to run if you are try to conserve storage space. In this service you can specify the number of days over which Nexus will look for activity before making the decision to evict an artifact. (See note about deletion.)

Optimize Repository Index

To speed up searches in Nexus, this task tells the internal search engine to optimize its index files. This has no affect on the indexes published by Nexus. Typically, this task does not have to run more than once a week.

Publish Indexes

Just as Maven downloads an index from a remote repository, Nexus can publish an index in the same format. This will make it easier for people using m2eclipse or Nexus to interact with your repositories.

Purge Nexus Timeline

Nexus maintains a lot of data that relates to the interaction between itself, proxied remote repositories, and clients on Nexus. While this information can be important for purposes of auditing, it can also take up storage space. Using this scheduled task you can tell Nexus to periodically purge this information. (See note about deletion.)

Rebuild Repository Attributes

This scheduled task tells Nexus to walk every file in a repository and gather information like checksums and file contents for every file.

Reindex Repositories

This service tells Nexus to reindex a repository.

Remove Snapshots from a Repository

Often, you will want to remove snapshots from a snapshot repository to preserve storage space. Note that configuring and running this job is not enough to reclaim disk space. You will also need to configure a scheduled job to empty the trash folder. Files are not deleted by the Remove Snapshots job, they are only moved into the Trash folder. When you create a scheduled task to remove snapshots, you can specify: <itemizedlist>

Minimum Snapshots to preserve in a repository - This configuration option allows you to specify a minimum number of SNAPSHOTs to preserve per artifact. For example, if you configured this option with a value of 2, Nexus will always preserve at least two SNAPSHOT artifacts.

Snapshot Retention (in days) - This configuration option allows you to specify the number of days to retain SNAPSHOT artifacts. For example, if you want to make sure that you are always keeping the last three day’s worth of SNAPSHOT artifacts, configure this option with a value of 3.

Whether snapshots should be removed if an artifact has been released - If your Nexus repository also contains a release repository, you can configure Nexus to remove all SNAPSHOT artifacts once an artifact has been released.

Synchronize Shadow Repository

This service synchronizes a shadow (or virtual) repository with its master repository.

Note The Evict and Purge actions do not delete data from the Nexus working directory. They simply move data to be cleared or evicted to a trash directory under the Nexus work directory. If you want to reclaim disk space, you need to clear the Trash on the Browse Repositories screen. If something goes wrong with a evict of clear service, you can move the data back to the appropriate storage location from the trash. You can also schedule the Empty Trash service to clear this directory on a periodic basis.

When you create a new service you can configure it to apply to all repositories, the repositories in a Nexus Group, or a specific Nexus Repository. A service can be scheduled to run once at a specific date and time, or periodically once every Day, Week, or Month. If none of these options suit your specific needs, you can select a recurrence of "Advanced" which will allow you to supply your own cron expression to specify when the job should execute. To create a new scheduled task, click on Scheduled Tasks under the Administration menu, and click on the Add button. This will bring up the screen shown in <xref linkend="fig-repomap-scheduled" />.

Managing Nexus Scheduled Tasks

figs/web/repository-manager_schedule-service.png <imageobject

Managing Configuration Backups with a Scheduled Task

Nexus Professional includes a scheduled task which allows you to create automated, scheduled backups of your Nexus configuration. This scheduled job will archive the contents of the sonatype-work/nexus/conf directory. <xref linkend="fig-configuring-schedule-conf-backup" /> shows a scheduled configuration backup job configured to backup the contents of the Nexus configuration every day at 12:15 AM.

figs/web/configuring_schedule-conf-backup.png
Figure 56. Configuring a Scheduled Backup of Nexus Configuration

Once a backup has been run, the contents of the backup will be available in <filename>sonatype-work/nexus/backup in a series of ZIP archives which include the date and a timestamp.

Managing Security

Nexus has role-based access control (RBAC) which gives administrators very fine-grained control over who can read from a repository (or a subset of repositories), who can administer the server, and who can deploy to repositories. The security model in Nexus is also so flexible as to allow you to specify that only certain users or roles can deploy and manage artifacts in a specific repository under a specific groupId or asset class. The default configuration of Nexus ships with four roles and four users with a standard set of permissions that will make sense for most users. As your security requirements evolve, you’ll likely need to customize security settings to create protected repositories for multiple departments, or development groups. Nexus provides a security model which can adapt to any scenario. Nexus' Role-based access control (RBAC) system is designed around the following four security concepts:

Privileges

Privileges are rights to read, update, create, or manage resources and perform operations. Nexus ships with a set of core privileges which cannot be modified, and you can create new privileges to allow for fine-grained targeting of role and user permissions for specific repositories.

Targets

Privileges are usually associated with resources or targets. In the case of Nexus, a target can be a specific repository or a set of repositories grouped in something called a repository target. A target can also be a subset of a repository or a specific asset classes within a repository. Using a target you can apply to a specific privilege to apply to a single groupId.

Roles

Collections of privileges can be grouped into roles to make it easier to define collections of privileges common to certain classes of users. For example, deployment users will all have similar sets of permissions. Instead of assigning individual privileges to individual users, you use Roles to make it easier to manage users with similar sets of privileges. A role has one or more privilege and/or one or more roles.

Users

Users can be assigned roles and privileges, and model the individuals who will be logging into Nexus and read, deploying, or managing repositories.

Managing Privileges

Nexus has three types of privileges: application privileges which cover actions a user can execute in Nexus, repository target privileges which govern the level of access a user has to a particular repository or repository target, and repository view privileges which control whether a user can view a repository. Behind the scenes, a privilege is related to a single REST operation and method like create, update, delete, read.

figs/web/repository-manager_security-privileges.png
Figure 57. Managing Security Privileges

To create a new privilege, click on the Add… button in the Privileges panel and choose Repository Target privilege. Creating a privilege will load the New Repository Target Privilege form shown in <xref linkend="fig-configuring-new-privilege" />. This form takes a privilege name, a privilege description, the repository to target, and a repository target.

figs/web/repository-manager_security-privileges-2.png
Figure 58. Managing Security Privileges

Once you create a new privilege, it will create four underlying privileges: create, delete, read, and update. The four privileges created by the form in <xref linkend="fig-configuring-new-privilege" /> are shown in <xref linkend="fig-configuring-new-privileges" />.

figs/web/repository-manager_security-privileges-3.png
Figure 59. Create, Delete, Read, and Update Privileges Created

Managing Repository Targets

A target is a set of regular expressions to match on a path (exactly how the route rules work now). This allows you to define for example a target called Apache Maven which is "org/apache/maven/.*" You can then add a new privilege that relates to the target and controls the CRUD operations for artifacts matching that path (the privilege can span multiple repositories if you want). You could thus delegate all control of org.apache.maven targets to a "Maven" team. In this way, you don’t need to create separate repositories for each logical division of your artifacts.

figs/web/repository-manager_repository-targets.png
Figure 60. Managing Repository Targets
figs/web/repository-manager_repository-targets-2.png
Figure 61. Managing Repository Targets

Managing Security Roles

Nexus ships with four roles: Nexus Administrator Role, Nexus Anonymous Role, Nexus Developer Role, and Nexus Deployment Role. Click on the Roles link under Security in the Nexus menu to show the list of roles shown in <xref linkend="fig-configuring-security-roles" />.

figs/web/repository-manager_security-roles.png
Figure 62. Managing Security Roles

To create a new role, click on the Add… button and fill out the New Nexus Role form shown in <xref linkend="fig-configuring-creating-new-role" />. When creating a new role, you will need to supply a role identifier, a role name, a description, and a session timeout. Roles are comprised of other roles and individual privileges, to assign a role or privilege to a role, click on the role or privilege under Available Roles/Privileges and drag the role or privilege to the Selected Roles/Privileges list.

figs/web/repository-manager_security-roles-3.png
Figure 63. Managing Security Roles

The built-in roles Nexus Administrator Role, Nexus Anonymous Role, Nexus Deployment Role, and Nexus Developer Role are managed by Nexus and cannot be edited or deleted. Selecting one of these built-in roles will load the form shown in <xref linkend="fig-configuring-builtin-role" />.

figs/web/repository-manager_security-roles-2.png
Figure 64. Managing Security Roles

A Nexus role is comprised of other Nexus roles and individual Nexus privileges. To view the component parts of a Nexus Role, select the role in the Roles panel and then choose the Role Tree tab as shown in <xref linkend="fig-configuring-role-tree" />.

figs/web/repository-manager_security-roles-4.png
Figure 65. Managing Security Roles

With the Repository Targets, you have fine grained control over every action in the system. For example you could make a target that includes everything except sources (.(?!-sources)\.) and assign that to one group while giving yet another group access to everything. This means you can host your public and private artifacts in a single repository without giving up control of your private artifacts.

Managing Users

Nexus ships with three users: admin, anonymous, and deployment. The admin user has all privileges, the anonymous user has read-only privileges, and the deployment user can both read and deploy to repositories. If you need to create users with a more focused set of permissions, you can click on Users under Security in the left-hand navigation menu. Once you see the list of users, you can click on a user to edit that specific user’s user ID, name, email, or status. You can also assign or revoke specific roles or permissions for a particular user.

figs/web/repository-manager_security-users.png
Figure 66. Managing Users

A user can be assigned one or more roles which in turn can include references to other Nexus roles or to individual Nexus privileges. To view a tree of assigned Nexus roles and privileges, select the Role Tree for a particular user as shown in <xref linkend="fig-configuring-security-user-role-tree" />.

figs/web/repository-manager_security-users-role-tree.png
Figure 67. Nexus User Role Tree

If you need to find out exactly how a particular user has been granted a particular privilege, you can use the Privilege Trace pane as shown in <xref linkend="fig-configuring-security-user-priv-trace" />. The Privilege Trace pane lists all of the privileges that have been granted to a particular user. Clicking on a privilege loads a tree of roles that grant that particular privilege to a user. If a user has been assigned a specific privilege by more than one Role or Privilege assignment, you will be able to see this reflected in the Role Containment list.

figs/web/repository-manager_security-users-privilege.png
Figure 68. Nexus User Privilege Trace

Network Configuration

By default, Nexus listens on port 8081. You can change this port, by changing the value in shown in <xref linkend="ex-plexus-props" />. To change the port, stop Nexus, change the value of applicationPort in this file, and then restart Nexus. Once you do this, you should see a log you that Nexus is listening on the altered port.

Contents of conf/plexus.properties
applicationPort=8081
runtime=\${basedir}/runtime
apps=\${runtime}/apps
work=\${runtime}/work
webapp=\${runtime}/apps/nexus/webapp
nexus.configuration=\${runtime}/apps/nexus/conf/nexus.xml

Nexus Logging Configuration

You can configure the format and level of logging from within the Nexus interface. To do this, click on Log Configuration under the Administration menu in the left-hand navigation menu. Clicking on this link will display the panel shown in <xref linkend="fig-configuring-log-config" />.

figs/web/repository-manager_log-config.png
Figure 69. The Log Configuration Panel

From this panel you can configure the following logging configuration properties:

Root Logger Level

This controls how verbose the Nexus logging will be. If set to DEBUG, Nexus will be very verbose printing all log messages include debugging statements. If set to ERROR, Nexus will be far less verbose only printing out a log statement if Nexus encounters an error.

File Appender Pattern

This field controls the format of each log line. This field’s format corresponds to the format expected by a Log4J PatternAppender. For more information about this format, refer to the Javadoc for Log4J’s PatternAppender.

The other configuration parameters: Root Logger Appenders and File Append Location, are not editable in this release of Sonatype Nexus.

Managing Nexus Plugins

Use the Nexus Plugin Console to list all installed Nexus plugins and browse REST services made available by installed Nexus Plugin. To open the Nexus Plugin Console, click on the Plugin Console link in the Administration section of the Nexus menu as shown in <xref linkend="fig-configuring_plugin-console-admin-menu" />.

figs/web/configuring_plugin-console-admin-menu.png
Figure 70. Administrative Menu Link for the Plugin Console

Once you open the Nexus Plugin Console, you will see a list of plugins installed in your Nexus installation. Clicking on a Nexus plugin in this list will display information about the plugin including: the plugin’s name, the plugin version, status, a description, SCM information about the plugin, and the URL of the plugin’s project web site.

figs/web/configuring_plugin-console.png
Figure 71. Nexus Plugin Console

Once you have selected a plugin from the list of installed plugin, you can browse the available REST interfaces by selecting the REST Services tab as shown in <xref linkend="fig-configuring_plugin-console-rest" />. Each plugin can contribute one or more REST services to Nexus.

figs/web/configuring_plugin-console-rest.png
Figure 72. Nexus Plugin Console Displaying REST endpoints for a Plugin

Nexus LDAP Integration

Nexus Open Source has a Lightweight Directory Access Protocol (LDAP) Authentication realm which provides Nexus with the capability to authenticate users against an LDAP server. In addition to handling authentication, Nexus can be configured to map Nexus roles to LDAP user is a member of a group that matches the ID of a Nexus role, Nexus will grant that user the matching Nexus Role. In addition to this highly configurable user and group mapping capability, Nexus can augment LDAP group membership with Nexus-specific user-role mapping.

Nexus Professional offers LDAP support features for enterprise LDAP deployments including the ability to cache authentication information, support for multiple LDAP servers and backup mirrors, the ability to test user logins, support for common user/group mapping templates, and the ability to support more than one schema across multiple servers.

Enabling the LDAP Authentication Realm

Authentication realm, you will need to add the Nexus LDAP Authentication Realm to the Selected Realms in the Security section of the Server configuration panel. To load the Server configuration panel, click on the Server link under Administration in the Nexus menu. Once you have the Server configuration panel loaded, select OSS LDAP Authentication Realm in the Available Realms list under the Security section and click the Add button (or Left Arrow) as shown in <xref linkend="fig-ldap-selecting-realm" xrefstyle="select: label" />.

Adding the LDAP Authentication Realm to Available Realms

figs/web/ldap_moving_ldap_realm_over.png

Next, click on the Save button in the Server configuration panel. To make sure that your Nexus instance attempts to authenticate against LDAP first, click on the OSS LDAP Authentication Realm in the Selected Realms list and drag it to the top of the list as shown in <xref linkend="fig-ldap-move-realm-to-top" xrefstyle="select: label" />. This will ensure that Nexus will consult the LDAP Server before it consults the other Authentication Realms.

Note Nexus will continue to fall-back to the Xml Authenticating Realm if it cannot authenticate a user against the LDAP server. If your LDAP server is unavailable, and you need to reconfigure the LDAP connection, you can always login as the default admin
Move the LDAP Authentication Realm to the Top of Selected

figs/web/ldap_moving_ldap_realm_to_top.png

Configuring Nexus LDAP Integration

To configure LDAP integration, click on the LDAP Configuration link in the Nexus menu as shown in <xref linkend="fig-ldap-config-link" xrefstyle="select: label" />. LDAP Configuration is under Security in the Nexus menu.

Clicking on the LDAP Configuration link will load the LDAP Configuration panel as shown in <xref linkend="fig-ldap-connection-authentication" xrefstyle="select: label" /> and <xref linkend="fig-ldap-user-mapping" xrefstyle="select: label" />. The following sections outline the configuration options available in the LDAP Configuration Panel.

Connection and Authentication

The following figure shows Nexus configured to connect to an LDAP server running on localhost port 10389 using the search base of "ou=system". On a more standard installation, you would likely not want to use Simple Authentication as it sends the password in clear text over the network, and you would also use a search base which corresponds to your organization’s top-level domain components such as "dc=sonatype,dc=com".

figs/web/ldap_configure_connection_and_authentication.png

<xref linkend="tbl-ldap-connection-config" xrefstyle="select: label" /> and <xref linkend="tbl-ldap-authentication-config" xrefstyle="select: label" /> contain detailed descriptions of the configuration fields in both the Connection and Authentication sections of the LDAP Configuration panel.

Table 2. Connection Configuration for LDAP Integration

Field Name

Description

Protocol

Valid values in this dropdown are ldap and ldaps which correspond to the Lightweight Directory Access Protocol and the Lightweight Directory Access Protocol over SSL

Hostname

The hostname or IP address of the LDAP

Port

The port on which the LDAP server is listening. Port 389 is the default port for the ldap protocol, and port 636 is the default port for the ldaps

Table 3. Authentication Configuration for LDAP Integration

Field Name

Description

Authentication Method

Nexus provides four distinct authentication methods to be used when connecting to the LDAP Server:

Simple Authentication:: Simple authentication is not recommended for production deployments not using the secure ldaps protocol as it sends a cleartext password over the network.

Anonymous Authentication:: Used when Nexus only needs read-only access to non-protected entries and attributes when binding to the LDAP

Digest-MD5:: This is an improvement on the CRAM-MD5 authentication method. For more information, see http://www.ietf.org/rfc/rfc2831.txt

CRAM-MD5:: The Challenge-Response Authentication Method (CRAM) based on the HMAC-MD5 MAC algorithm. In this authentication method, the server sends a challenge string to the client, the client responds with a username followed by a Hex digest which the server compares to an expected value. For more information, see RFC 2195

For a full discussion of LDAP authentication approaches, see http://www.ietf.org/rfc/rfc2829.txt and http://www.ietf.org/rfc/rfc2251.txt

SASL Realm

The Simple Authentication and Security Layer (SASL) Realm to connect with. The SASL Realm is only available if the authentication method is Digest-MD5 or CRAM-MD5.

Username

Username of an LDAP User to connect (or bind) with. This is a Distinguished Name of a user who has read access to all users and groups

===User and Group Mapping

The LDAP Configuration panel also contains sections to manage User Element Mapping and Group Element Mapping as shown in <xref linkend="fig-ldap-user-mapping" xrefstyle="select: label" />.

figs/web/ldap_configure_user_mapping.png

The fields for both the User Element Mapping and Group Element Mapping sections are described in detail in <xref linkend="tbl-ldap-user-element-config" xrefstyle="select: label" /> and <xref linkend="tbl-ldap-group-element-config" xrefstyle="select: label" />.

Table 4. User Element Mapping Configuration for LDAP Integration

Field Name

Description

Base DN

Corresponds to the Base DN containing user entries. This DN is going to be relative to the Search Base which was specified in <xref linkend="fig-ldap-connection-authentication" xrefstyle="select: label" />. For example, if your users are all contained in "ou=users,dc=sonatype,dc=com" and you specified a Search Base of "dc=sonatype,dc=com" you would use a value of "ou=users"

User Subtree

True if there is a tree below the Base DN which can contain user entries. False if all users are contain within the specified Base DN. For example, if all users are in "ou=users,dc=sonatype,dc=com" this field should be false. If users can appear in organizational units within organizational units such as "ou=development,ou=users,dc=sonatype,dc=com" this field should be true.

Object Class

This value defaults to inetOrgPerson which is a standard object class defined in <ulink url="http://www.faqs.org/rfcs/rfc2798.html">RFC 2798. inetOrgPerson contains standard fields such as mail, uid. Other possible values are posixAccount or a custom class.

User ID Attribute

This is the attribute of the Object class which supplies the User ID. Nexus will use this attribute as the Nexus User ID.

Real Name Attribute

This is the attribute of the Object class which supplies the real name of the user. Nexus will use this attribute when it needs to display the real name of a user.

E-Mail Attribute

This is the attribute of the Object class which supplies the email address of the user. Nexus will use this attribute when it needs to send an email to a user.

Password Attribute

This is the attribute of the Object class which supplies the password of the user. Nexus will use this attribute when it is authenticating a user against an LDAP server.

Password Encoding

Table 5. Group Element Mapping Configuration for LDAP Integration

Field Name

Description

Group Type

Groups are generally one of two types in LDAP systems - static or dynamic. A static group contains a list of users. A dynamic group is where the user contains a list of groups the user belongs to. In LDAP a static group would be captured in an entry with an Object class groupOfUniqueNames which contains one or more uniqueMember attributes. In a dynamic group configuration, each user entry in LDAP contains an attribute which lists group membership.

Base DN

This field is similar to the Base DN field described in <xref linkend="tbl-ldap-user-element-config" xrefstyle="select: label" />. This field is visible if Static Groups is selected. If your groups were defined under "ou=groups,dc=sonatype,dc=com", this field would have a value of "ou=groups

Group Subtree

This field is similar to the User Subtree field described in <xref linkend="tbl-ldap-user-element-config" xrefstyle="select: label" />. If all groups are defined under the entry defined in Base DN, this field should be false, if a group can be defined in a tree of organizational units under the Base DN, this field should be true. This field is visible if Static Groups is selected.

Object Class

This value defaults to groupOfUniqueNames which is a standard object class defined in <ulink url="http://www.faqs.org/rfcs/rfc2798.html">RFC 4519. groupOfUniqueNames is simply a collection of references to unique entries in an LDAP directory and can be used to associate user entries with a group. Other possible values are posixGroup or a custom class. This field is visible if Static Groups is selected.

Group ID Attribute

Specifies the attribute of the Object class which specifies the Group ID. If the value of this field corresponds to the ID of a Nexus Role, members of this group will have the corresponding Nexus privileges. Defaults to "cn". This field is visible if Static Groups is selected.

Group Member Attribute

Specifies the attribute of the Object class which specifies a member of a group. A groupOfUniqueNames has multiple uniqueMember attributes for each member of a group. Defaults to "uniqueMember". This field is visible if Static Groups is selected.

Group Member Format

This field captures the format of the Group Member Attribute and it is used by Nexus to extract a username from this attribute. For example, if the Group Member Attribute has the format "uid=brian,ou=users,dc=sonatype,dc=com", then the Group Member Format would be If the Group Member Attribute had the format "brian", then the Group Member Format would be Groups is selected.

Member of Attribute

If your installation does not use Static Groups, you can configure Nexus LDAP Integration to refer to an attribute on the User entry to derive group membership. To do this, select Dynamic Groups in the Group Type field in Group Element Mapping. Selecting Dynamic Groups will show a single field named Member of Attribute as shown in <xref linkend="fig-ldap-dynamic-groups" xrefstyle="select: label" />.

figs/web/ldap_dynamic_groups.png

Mapping Users and Groups with Active Directory

When mapping users and groups to an Active Directory installation, try the common configuration values listed in <xref linkend="tbl-ldap-ad-user-element" /> and <xref linkend="tbl-ldap-ad-group-element" />.

Table 6. Connection and Authentication Configuration for Active Directory

Configuration Element

Configuration Value

Protocol

ldap

Hostname

Hostname of Active Directory Server

Port

389 (or port of AD server)

Search Base

DC=yourcompany,DC=com (customize for your organization)

Authentication

Simple Authentication

Username

CN=Administrator,CN=Users,DC=yourcompany,DC=com

Table 7. User Element Mapping Configuration for Active Directory

Configuration Element

Configuration Value

Base DN

cn=users

User Subtree

false

Object Class

user

User ID Attribute

sAMAccountName

Real Name Attribute

cn

E-Mail Attribute

mail

Password Attribute

(Not Used)

Password Encoding

Crypt

Table 8. Group Element Mapping Configuration for Active Directory

Configuration Element

Configuration Value

Group Type

Dynamic Groups

Member Of Attribute

memberOf

Configuring Nexus LDAP for Active Directory

figs/web/ldap_active-directory.png

Warning You should connect to the AD through port 3268 if you have a multidomain, distributed Active Directory forest. Connecting directly to port 389 might lead to errors.

Mapping Users and Groups with posixAccount

When mapping users and groups to LDAP entries of type posixAccount, try the common configuration values listed in <xref linkend="tbl-ldap-posix-user-element" /> and <xref linkend="tbl-ldap-posix-group-element" />.

Table 9. User Element Mapping Configuration for posixAccount

Configuration Element

Configuration Value

Base DN

(Not Standard)

User Subtree

false

Object Class

posixAccount

User ID Attribute

sAMAccountName

Real Name Attribute

uid

E-Mail Attribute

mail

Password Attribute

(Not Used)

Password Encoding

(Not Used)

Table 10. Group Element Mapping Configuration for posixGroup

Configuration Element

Configuration Value

Group Type

Static Groups

Base DN

(Not Standard)

Group Subtree

false

Object Class

posixGroup

Group ID Attribute

cn

Group Member Attribute

memberUid

Group Member Format

===Mapping Roles to LDAP Users

Once User and Group Mapping has been configured, you can start verifying how LDAP users and groups are mapped to Nexus Roles. If a user is a member of an LDAP group that has a Group ID corresponding to the ID of a Nexus Role, that user is granted the appropriate permissions in Nexus. For example, if the LDAP user entry in "uid=brian,ou=users,dc=sonatype,dc=com" is a member of a groupOfUniqueNames attribute value of admin, when this user logs into Nexus, it will be granted the Nexus Administrator Role if Group Element Mapping is configured properly. To verify the User Element Mapping and Group Element Mapping, click on Check User Mapping in the LDAP Configuration panel directly below the Group Element Mapping section, <xref linkend="fig-ldap-verify-user-mapping" xrefstyle="select: label" /> shows the results of this check.

Checking the User and Group Mapping in LDAP Configuration

figs/web/ldap_verifying_user_mapping.png

In <xref linkend="fig-ldap-verify-user-mapping" xrefstyle="select: label" />, Nexus LDAP Integration locates a user with a User ID of "brian" who is a member of the "admin" group. When brian logs in, he will have all of the rights that the admin Nexus Role has.

Mapping Nexus Roles for External Users

If you are unable to map all of the Nexus roles to LDAP groups, you can always augment the Role information by adding a specific user-role mapping for an external LDAP user in Nexus. In other words, if you need to make sure that a specific user in LDAP gets a specific Nexus role and you don’t want to model this as a group membership, you can add a role mapping for an external user in Nexus. Nexus will keep track of this association independent of your LDAP server. Nexus continues to delegate authentication to the LDAP server for this user, Nexus will continue to map the user to Nexus roles based on the group element mapping you have configured, but Nexus will also add any roles specified in the User panel. You are augmenting the role information that Nexus gathers from the group element mapping.

Once the User and Group Mapping has been configured, click on the Users link under Security in the Nexus menu. The Users tab is going to contain all of the "configured" users for this Nexus instance as shown in <xref linkend="fig-ldap-all-configured-users-initial" />. A configured user is a user in a Nexus-managed Realm or an External User which has an explicit mapping to a Nexus role. In <xref linkend="fig-ldap-all-configured-users-initial" />, you can see the three default users in the Nexus-managed default realm plus the brian user from LDAP. The brian user appears because this user has been mapped to a Nexus role.

Viewing All Configured Users

figs/web/ldap_ad_all_configured_users_initial.png

The list of users in <xref linkend="fig-ldap-all-configured-users-initial" /> is a combination of all of the users in the Nexus default realm and all of the External Users with role mappings. To explore these two sets of users, click on the All Configured Users dropdown and choose "Default Realm Users". Once you select this, click in the search field and press Enter. Searching with a blank string in the Users panel will return all of the users of the selected type. In <xref linkend="fig-ldap-all-default-realm" /> you see a dialog containing all three default users from the Nexus default realm.

All Default Realm Users

figs/web/ldap_ad_all_default_realm_users.png

If you wanted to see a list of all LDAP users, select "LDAP" from the "All Configured Users" dropdown shown in <xref linkend="fig-ldap-all-configured-users-initial" /> and click on the search button (magnifying glass) with an empty search field. Clicking search with an empty search field will return all of the LDAP users as shown in <xref linkend="fig-ldap-all-ldap-realm" />.

Note Note that the user "tobrien" does not show up in the "All Configured Users" list. This is by design. Nexus is only going to show you information about users with external role mappings. If an organization has an LDAP directory with thousands of developers, Nexus doesn’t need to retain any configuration information for users that don’t have custom Nexus role mappings.
All LDAP Users

figs/web/ldap_ad_all_ldap_realm_users.png

To add a mapping for an external LDAP user, you would click on the "All Configured Users" dropdown and select LDAP. Once you’ve selected LDAP, type in the user ID you are searching for and click the search button (magnifying glass icon to right of the search field). In <xref linkend="fig-ldap-search-ldap-users" />, a search for "brian" yields one user from the LDAP server.

Search LDAP Users

figs/web/ldap_ad_searching_ldap_users.png

To add a Nexus role mapping for the external user "brian" shown in <xref linkend="fig-ldap-search-ldap-users" />, click on the user in the results table and drag a role from Available Roles to Selected Roles as shown in <xref linkend="fig-ldap-mapping-deploy" />. In this case, the user "brian" is mapped to the Administrative group by virtue of his membership in an "admin" group in the LDAP server. In this use case, a Nexus administrator would like to grant Brian the Deployment Role without having to create a LDAP group for this role and modifying his group memberships in LDAP

Mapping the Deployment Role to an External User

figs/web/ldap_ad_mapping_ldap_deployment.png

The end result of this operation is to augment the Group-Role mapping that is provided by the LDAP integration. You can use LDAP groups to manage coarse-grained permissions to grant people administrative privileges and developer roles, and if you need to perform more targeted privilege assignments in Nexus you can Map LDAP users to Nexus roles with the techniques shown in this section.

Mapping External Roles to Nexus Roles

Nexus makes it very straightforward to map an external role to an internal Nexus role. This is something you would do, if you want to grant every member of an externally managed group (such as an LDAP group) a certain privilege in Nexus. For example, assume that you have a group in LDAP named "svn" and you want to make sure that everyone in the "svn" group has Nexus Administrative privileges. To do this, you would click on the Add.. dropdown in the Role panel as shown in <xref linkend="fig-ldap-select-ext-role-map" />. This dropdown can be found in the Role management panel which is opened by clicking on Roles in the Security menu.

Selecting External Role Mapping in the Role Management Panel

figs/web/ldap_mapping-external-role.png

Selecting External Role Mapping under Add… will show you a dialog which contains a dropdown of External Realms. Selecting an external realm such as LDAP will then bring up a list of roles managed by that external realm. The dialog shown in <xref linkend="fig-ldap-select-ext-role" /> shows the external realm LDAP selected and the role "svn" being selected to map to a Nexus role.

Selecting an Externally Managed Role to Map to a Nexus Role

figs/web/ldap_mapping-external-role-select.png

Once the external role has been selected, Nexus will create a corresponding Nexus Role. You can then assign other Roles to this new externally mapped Role. <xref linkend="fig-ldap-external-role-config" /> shows that the SVN role from LDAP is being assigned the Nexus Administrator Role. This means that any user that is authenticated against the external LDAP Realm who is a member of the svn LDAP group will be assigned a Nexus role that maps to the Nexus Administrator Role.

Mapping an External Role to a Nexus Role

figs/web/ldap_mapping-external-role-config.png

Enterprise LDAP Support

The following sections outline Enterprise LDAP features which are available in Nexus Professional. <section> Enterprise LDAP Failover Support When an LDAP server fails, the applications authenticating against it can also become unavailable. Because a central LDAP server is such a critical resource, many large software enterprises will install a series of primary and secondary LDAP servers to make sure that the organization can continue to operate in the case of an unforeseen failure. Nexus Professional’s Enterprise LDAP plugin now provides you with the ability to define multiple LDAP servers for authentication. To configure multiple LDAP servers, click on Enterprise LDAP under Security in the Nexus application menu. You should see the Enterprise LDAP panel shown in the following figure.

Defining Multiple LDAP Servers in Nexus Professional

figs/web/multiple-ldap-servers.png

You can use the Backup Mirror setting for an LDAP repository. This backup mirror is another LDAP server which will be consulted if the original LDAP server cannot be reached. Nexus Professional assumes that the backup mirror is a carbon copy of the original LDAP server, and it will use the same user and group mapping configuration as the original LDAP server. Instead of using the backup mirror settings, you could also define multiple LDAP backup mirrors in the list of configured LDAP servers shown in the previous figure. When you configure more than one LDAP server, Nexus Professional will consult the servers in the order they are listed in this panel. If Nexus can’t authenticate against the first LDAP server, Nexus Professional will move on to the next LDAP server until it either reaches the end of the list or finds an LDAP server to authenticate against.

Use Multiple LDAP Servers in a Failover Scenario

figs/web/ldap-backup.png

The feature just described is one way to increase the reliability of your Nexus instance. In the previous case, both servers would have the same user and group information. The secondary would be a mirror of the primary. But, what if you wanted to connect to two LDAP servers that contained different data? Nexus Professional also provides…

Support for Multiple Servers and LDAP Schemas

The same ability to list more than one LDAP server also allows you to support multiple LDAP servers which may or may not contain the same user authentication information. Assume that you had an LDAP server for the larger organization which contained all of the user information across all of the departments. Now assume that your own department maintains a separate LDAP server which you use to supplement this larger LDAP installation. Maybe your department needs to create new users that are not a part of the larger organization, or maybe you have to support the integration of two separate LDAP servers that use different schema on each server.

A third possibility is that you need to support authentication against different schema within the same LDAP server. This is a common scenario for companies which have merged and whose infrastructures has not yet been merged. To support multiple servers with different user/group mappings or to support a single server with multiple user/group mappings, you can configure these servers in the Enterprise LDAP panel shown above. Nexus will iterate through each LDAP server until it can successfully authenticate a user against an LDAP server.

Supporting Multiple LDAP Schemas with Nexus Professional

figs/web/ldap-multiple.png

Enterprise LDAP Performance Caching and Timeout

If you are constantly authenticating against a large LDAP server, you may start to notice a significant performance degradation. With Nexus Professional you can cache authentication information from LDAP. To configure caching, create a new server in the Enterprise LDAP panel, and scroll to the bottom of the Connect tab. You should see the following input field which contains the number of seconds to cache the results of LDAP queries.

Setting the LDAP Query Cache Duration (in Seconds)

figs/web/ldap-caching.png

You will also see options to alter the connection timeout and retry interval for an LDAP server. If you are configuring a number of different LDAP servers with different user and group mappings, you will want to make sure that you’ve configured low timeouts for LDAP servers at the beginning of your Enterprise LDAP server list. If you do this properly, it will take Nexus next to no time to iterate through the list of configured LDAP servers.

Setting the LDAP Connection Timeout (in Seconds)

figs/web/ldap-timeout.png

We improved the overall caching in this release. The cache duration is configurable and applies to authentication and authorization, which translates into pure speed! Once you’ve configured LDAP caching in Nexus Professional, authentication and other operations that involve permissions and credentials once retrieved from an external server will run in no time.

User and Group Templates

If you are configuring your Nexus Professional instance to connect to an LDAP server there is a very good chance that your server follows one of several, well-established standards. Nexus Professional’s LDAP server configuration includes these widely used user and group mapping templates which great simplify the setup and configuration of a new LDAP server. To configure user and group mapping using a template, select a LDAP server from the Enterprise LDAP panel, and choose the User and Group Settings. You will see a User & Group Templates section as shown in the following figure.

Using User & Group Mapping Templates

figs/web/ldap-templates.png

Testing a User Login

Nexus Professional provides you with the ability to test a user login directly. To test a user login, go to the User and Group Settings tab for a server listed in the Enterprise LDAP panel. Scroll to the bottom of the form, and you should see a button named “Check Login”.

Testing a User Login

figs/web/ldap-check-login.png

If you click on Check Login, you will then be presented with the login credentials dialog shown below. You can use this dialog to login as an LDAP user and test the user and group mapping configuration for a particular server. This feature allows you to test user and group mapping configuration directly. This feature allows you to quickly diagnose and address difficult authentication and access control issues via the administrative interface.

Supply a User’s Login Credentials

figs/web/ldap-login-credentials.png

Nexus Procurement Suite

Introduction

Nexus Procurement Suite provides an organization with control over what artifacts are allowed into a repository from an external, proxied repository such as the Maven Central Repository. Such control can be a prerequisite for organizations unwilling or unable to trust the entire contents of an external public repository. If an organization is developing mission critical code, they will likely want to subject every third party dependency to intense scrutiny and testing before making an artifact available to build a release or support a team of developers. In most Enterprise development environments, a developer can’t just decide to add in a new dependency to Hibernate or to the Spring Framework on a whim; the decision to add dependencies to third-party libraries will need to be funneled through an oversight process that relies on an architect or an administrator to promote artifacts to a certified release repository.

Another, more common experience is an organization which needs to proxy something like the Maven Central Repository but wants to limit access to specific versions of artifacts or prevent dependencies on everything contained under a specific group. Some organizations are more amenable to trusting the contents of a remote, proxied repository like Central, but they also need the ability to block certain dependencies. Maybe you work on a team that needs to limit access to dependencies with a certain license, or maybe you just want to make sure no one uses a problematic version of Hibernate with a known bug? The procurement suite is the tool that provides for both coarse and fine-grained control of the artifacts that can appear in a repository.

The Stages of Procurement

A procured repository is a Hosted Repository which procures artifacts from a Proxy Repository. For example, one could create a hosted repository named "Secured Maven Central" and then configure this hosted repository to procure artifacts from the "Maven Central" repository. Once the hosted repository has been created and the source of procurement has been configured, the repository will obtain artifacts from the proxy repository as long as procurement is activated. If you start procurement for a Hosted repository, the hosted repository will fetch artifacts from the Proxy repository specified in the procurement settings. If you stop procurement for a Hosted Repository, no additional artifacts will be retrieved from the Proxy repository specified in the procurement settings.

The ability to enable or disable procurement for a Hosted repository comes in very handy when you want to "certify" a Hosted repository as containing all of the artifacts (no more and no less) required for a production build. You can start procurement, run a build which triggers artifact procurement, and then stop procurement knowing that the procured repository now contains all of the artifacts required for building a specific project. Stopping procurement assures you that the contents of the repository will not change if the third-party, external proxied repository does. This is an extra level of assurance that your release artifacts depend on a set of artifacts under your complete control.

Two Approaches to Procurement

There are two main use cases for the Procurement Suite. In the first use case, the Procured Release Repository, the Procurement features of Nexus Professional are used to create a procured release repository to make sure that the organization has full control over the artifacts that are making it into a production release. The other use case, the Procured Development Repository, is for organizations that need more upfront control over which artifacts are allowed during the development of a project. The following sections describe these two uses cases in more detail. === Procured Release Repository

The Procurement Suite can be used in two different ways. In the "Procured Release" mode, developers work with a proxied 3rd party repository exactly as they would without the Procurement Suite. When a developer needs to add a dependency on a new artifact, Nexus will retrieve the artifact from the third-party repository (like Central or Apache Snapshots) and this artifact will be served to Maven via a proxied Nexus repository. When a QA or Release engineer needs to build a release or staging artifact, the Release or QA build would be configured to execute against a procured repository. A procured repository is one which only serves the artifacts which have been explicitly approved using the Procurement Suite.

Procurement to a Certified Release Repository

figs/web/procurement_release-procurement.png

In this model, developers can add as many third-party dependencies as they want, and it is the responsibility of the QA and Release engineers to approve (or procure) artifacts from the Development Repository to the QA/Release Repository. Developers can move forward, adding dependencies freely from a third-party, proxied repository, but once it is time to populate a Release repository, a Nexus administrator can audit the required artifacts, create a hosted repository, turn on procurement, populate the repository, and then deactivate procurement. This has the effect of "locking down" the artifacts that are involved in a production release.

Procured Development Repository

There are some development environments which require even more control over which artifacts can be used and referenced by developers. In these situations, it might make sense to only allow developers to work with a procured repository. In this mode, a developer must ask a Nexus administrator for permission to add a dependency on a particular third-party artifact. A Procurement Manager would then have to approve the artifact, or group of artifacts so that they would be made available to the developers. This is the "ask-first" model for organizations that want to control which artifacts make it into the development cycle.

Procurement to a Certified Development Repository

figs/web/procurement_ask-first-procurement.png

This is a model common in industries that have strict oversight requirements. More often than not, banks, hospitals, and government agencies have fairly strict regulations on the software that can be used by large development teams. With the Procured Development Repository approach, an architecture group can have full control over what artifacts can be referenced by a large development team.

Installing the Procurement Suite

If you installed Nexus Professional, the Nexus Procurement Suite is already installed. Just start Nexus and look for the Artifact Procurement option in the left-hand navigation menu of the Nexus interface. If you see the Artifact Procurement link as shown in <xref linkend="fig-procure-links" />, the Procurement Suite is available and ready to be configured.

Setting up a Procured Repository

This section will walk through the process of creating and configuring a hosted repository named "Procured Central" which will be procured from the "Maven Central" proxy repository. Setting up a procured repository consists of the following steps:

  • Enabling Remote Index Downloads for a Proxy Repository

  • Creating a Hosted Repository to be Procured

  • Configuring Procurement for the Hosted Repository

  • Configuring Procurement Rules

Before configuring a procured repository, you need to make sure that you have enabled Remote Index downloading for the proxied repository that will serve as the source for your procured repository.

Note If you are attempting to procure artifacts from a remote repository which does not have a repository index, you can still use the procurement suite. Without a remote repository index, you will need to configure procurement rules manually without the benefit of the already populated repository tree shown in <xref linkend="procure-sect-config-rule" />.

Enable Remote Index Downloads

When you configure procurement rules for a hosted repository, the administrative interface displays the repository as a tree of groups and artifacts populated from the Remote Repository’s Nexus Index. Nexus ships with a set of proxy repositories, but remote index downloading is disabled by default. To use procurement, you will need to tell Nexus to download the remote indexes for a proxy repository. Click on "Repositories" under Views/Repositories in the Nexus menu, then click on the Maven Central repository in the list of repositories. Click on the Configuration tab, locate Download Remote Indexes, and switch this option to "True" as shown in <xref linkend="fig-procure-enabling-remote" />.

Enabling Remote Index Downloads for a Proxy Repository

figs/web/procure_central-download-remote-index.png

Click on the Save button in the dialog shown in <xref linkend="fig-procure-enabling-remote" />. Right-click on the Index in the Repositories list and select "Re-Index". Nexus will then download the remote repository and recreate the index for any Repository Groups that contain this proxied repository. Nexus may take a few minutes to download the remote index for a large repository. Depending on your connection to the Internet, this process can take anywhere from under a minute to a few minutes. The size of the remote index for Maven Central is on the order of 30 MB. To check on the status of the remote index download, click on System Feeds under Views in the Nexus menu. Click on the last feed to see a list of "System Changes in Nexus". If you see a log entry like the one highlighted in <xref linkend="fig-procure-system-feed" />, Nexus has successfully downloaded the Remote Index from Maven Central.

Verification that the Remote Index has been Downloaded

figs/web/procure_reindex-system-feed.png

Create a Hosted Repository

When you configure procurement you are establishing a relationship between a Proxy repository and a Hosted repository. To create a Hosted repository, select Repositories from the Administration section of the Nexus menu, and click on the Add button selecting Hosted as shown in <xref linkend="fig-procure-add-hosted" />.

Adding a Hosted Repository

figs/web/procure_add-hosted.png

Selecting Hosted will then load the Repository Config form shown in <xref linkend="fig-procure-add-secured" />. Create a repository with a Repository ID of "secured" and a name of "Secured". Make the release policy "Release". Click the <guibutton>Save button to create the new Hosted Repository.

Adding the "Secured" Hosted Repository

figs/web/procure_after-add-secured.png

Configuring Procurement for Hosted Repository

At this point, the list of Repositories will have a new Hosted repository named "Secured". The next step is to start procurement for the new Secured repository. When you do this, you are establishing a relationship between the new Hosted repository and a Proxy repository. In this case, we’re configuring procurement for the Secured repository and we’re telling the Procurement Suite to procure artifacts from the Maven Central proxy repository. To configure this relationship and to start procurement, click on Artifact Procurement under the Enterprise menu. In the Procurement panel, click on Add Procurement Repository as shown in <xref linkend="fig-procure-starting-procurement" />.

Adding a Procured Repository

figs/web/procure_add-procured-repository.png

You will then be presented with the Start Procurement dialog as shown in <xref linkend="fig-procure-start-procurement-dialog" />. Select the "Maven Central" proxy repository from the list of available Source repositories.

.Configuring Procurement for a Hosted Repository figs/web/procure_configure-procurement-confirm.png Procurement is now configured and started, if you are using an instance of Nexus installed on localhost port 8081, you can configure your clients to reference the new Secured repository at http://localhost:8081/nexus/content/repositories/secured

By default, all artifacts are denied and without further customization of the procurement rules no artifacts will be available in the new Secured repository.

One interesting thing to note about the "Secured" repository is that the Repository Type changed, once procurement was started. When procurement is activate for a Hosted repository, the repository will show up in the Nexus interface as a Proxy repository. Click refresh in the Repositories list, and look at the Secured repository in the list of repositories, you will see that the repository type column contains "proxy" as shown in <xref linkend="fig-procure-hosted-now-proxy" />. When procurement is started for a hosted repository it is effectively a proxy repository, and when it is stopped it will revert back to being a normal hosted repository.

Hosted Repository is a Proxy Repository while Procurement is Active

figs/web/procured_started-now-proxy.png

Procured Repository Administration

Once you’ve defined the relationship between a Hosted repository and a Proxy repository and you have started procurement, you can start defining the rules which will control which artifacts are allowed in a procured repository and which artifacts are denied. You can also start and stop procurement. This section details some of the administration panels and features which are available for a procured repository.

Viewing the Procurement Management Interface

A procurement rule is a rule to allow or deny the procurement of a group, artifact, or a collection of groups or artifacts. You load the Artifact Procurement interface by selecting Artifact Procurement under the Enterprise section of the Nexus menu. Clicking on this link will load a list of procured repositories. Clicking on the repository will load the entire repository in a tree as shown in <xref linkend="fig-procure-repository-view" />. This section will illustrate the steps required for blocking access to an entire artifact and then selectively allowing access to a particular version of that same artifact. This is a common use-case in organizations which want to standardize on specific versions of a particular dependency.

Note If you are attempting to procure artifacts from a remote repository which does not have a repository index, you can still use the procurement suite. Without a remote repository index, you will need to configure procurement rules manually without the benefit of the already populated repository tree shown in this section.
Viewing a Repository in the Artifact Procurement Interface

figs/web/procure_repository-view.png

The directory tree in <xref linkend="fig-procure-repository-view" /> is the index of the proxy repository from which artifacts are being procured.

Configuring a Procurement Rule

To configure a procurement rule, right click on a folder in the tree. <xref linkend="fig-procure-deny-group-all" /> displays the procurement interface after right clicking on the jython artifact folder. In this dialog, we are telling the procurement interface to deny everything in the jython group and its sub-groups. If you attempt to retrieve any version under the jython artifact after this rule is created, the Procurement Suite will prevent access to this artifact. For example, if you attempt to build a project that depends on jython:jython:2.1, it will not be made available via the Secured repository created in <xref linkend="procure-sect-configure" />.

Denying Procurement for Everything Under a Group

figs/web/procure_deny-all-jython.png

After denying access to the entire jython artifact, right-click on the 2.1 version folder under the jython artifact folder. Select "Exactly the artifact" as shown in <xref linkend="fig-procure-allowing-artifact" /> to allow for the procurement of only the 2.1 version. This has the effect of creating a specific rule which allows the procurement of a single version of the jython:jython artifact.

Allowing Access to a Single Artifact in a Denied Group

figs/web/procure_approve-artifact.png

After allowing this element, your procurement tree is going to contain red and green markers on the affected folders as shown in <xref linkend="fig-procure-composite-effects" />. While the jython artifact folder has a red slash through it the 2.1 version folder has a green check. You have configured the Procurement Suite to deny access to all versions of the jython artifact except version 2.1.

Viewing the Effect of Composite Procurement Rules on the Tree

figs/web/procure_only-one-jython.png

Managing Procurement Rules

Once you’ve created a set of procurement rules you are going to want to know how to view the procurement rules which are applicable to a particular node. Procurement rules will frequently overlap; for example, in <xref linkend="procure-sect-creating-rules" />, there are two rules: one rule applies to all of the versions (folder) below the jython artifact folder, and the other rule applies to a particular version directory. Since rules can overlap, Nexus provides a simple way to list and manage the rules which apply to a specific node in the directory tree. <xref linkend="fig-procure-composite-effects" /> shows the resolved procurement rules after clicking on the Jython 2.1 version artifact from <xref linkend="procure-sect-configure" />.

Effective Procurement Rules for a Particular Node

figs/web/procure_effective-rules.png

This dialog gives the procurement administrator a fine-grained view into the rules that apply to a particular node. From this dialog you can remove rules which apply to a specific node.

Stopping Procurement

Some organizations may want to "lock down" the artifacts that a release build can depend upon, and it is also a good idea to make sure that your build isn’t going to be affected by changes to a repository not under you control. A procurement administrator might configure a procured repository, start procurement, and run an enterprise build against the repository to populate the procured, hosted repository with all of the necessary artifacts. After this process, the procurement administrator can stop procurement and continue to run the same release build against the hosted repository which now contains all of the procured artifacts.

To stop procurement, go to the Artifact Procurement management interface by clicking on Artifact Procurement under the Enterprise section of the Nexus menu. Right click on the repository and choose Stop Procurement as shown in <xref linkend="fig-procure-stopping" />.

Stopping Procurement for a Procured Repository

figs/web/procure_stop-procurement.png

After choosing Stop Procurement, you will then see a dialog confirming your decision to stop procurement as shown in <xref linkend="fig-procure-stop-confirm" />.

Stop Procurement Confirmation Dialog

figs/web/procure_stop-procurement-confirm.png

Once procurement is stopped, the Secure repository will revert back to being a plain-old Hosted repository. You can validate this by looking at the repository type in the list of repositories.

Build Promotion with the Nexus Staging Suite

Introduction

If you release software, you will often need to test a release before deploying it to a production system or an externally accessible repository. For example, if you are developing a large, enterprise web application you may want to stage a release candidate to a production system and perform a series of rigorous tests before a release manager makes a decision to either return a system to development or deploy a system to production.

The Nexus Staging Suite in Nexus Professional allows an organization to create a temporary staging repository and to manage the promotion of artifacts from a staging repository to a release repository. This ability to create an isolated, release candidate repository that can discarded or promoted makes it possible to support the decisions that go into certifying a release.

Releasing Software with a Staging Repository

Without the Staging Suite, when a developer deploys an artifact to a Hosted repository such as the Release repository, this artifact is published to a hosted repository and is immediately made available - there is no oversight, there is no approval or certification process. There is no chance to test the artifact before writing the artifact to a hosted repository. If there is a mistake in the release, often the only option available is to republish the artifacts to the release repository or deploy a new version of the artifacts.

Without the Nexus Staging Suite

figs/web/staging_without_staging.png

While this is acceptable for some users, organizations and enterprises with a QA cycle often need a temporary staging repository for potential release candidates: a staging repository. With the Nexus Staging Suite, an organization can automatically stage releases to a temporary repository which can then be used to test and certify a set of artifacts before they are published to a final release repository. This temporary repository can then be promoted as a whole or dropped depending on the results of testing.

How the Staging Suite Works

Here’s how staging works in Nexus Professional:

  1. A developer deploys an artfiact (or a set of artifacts) to Nexus Professional.

  2. The Staging Suite intercepts this deployment and matches the artifact’s path against a set of Staging Profiles.

  3. If the path of the artifact activates a staging profile, a temporary staging repository is created and the artifacts are deployed to this repository.

  4. Once the developer has deployed a set of artifacts to Nexus, they will then "Close" the staging repository.

  5. The Staging Suite will then add this temporary staging repository to one or more Target Repository Groups.

Once the staging repository is closed, and the staging repository has been added to a Target repository group, the artifacts in the staging repository are then made available to developers or testers via a repository group. Tests can be performed on the artifacts as if they were already published in a hosted repository. From this point, one of two things can happen to a staging repository:

Release

A Nexus user can "release" a staging repository and select a hosted repository to publish artifacts to. Releasing the contents of a repository publishes all artifacts from the staging repository to a hosted repository and deletes the temporary staging repository.

Drop

A Nexus user can "drop" a staging repository. Dropping a staging repository will remove it from any groups and delete the temporary staging repository.

Promote

If your Nexus installation contains Build Promotion profiles, you will also see an option to "promote" a staging repository to a Build Promotion Group. When you promote a staging repository you can expose the contents of that staging repository via additional groups. Build Promotion profiles are explained in detail in the next section.

With Nexus Staging Suite

figs/web/staging_with_staging.png

Supplying a Description for a Staging Release

figs/web/staging-workflow.png

Multi-level Staging and Build Promotion

Nexus Professional also supports multi-level staging and build promotion. With multi-level staging, a staging repository can be tested and then promoted to a separate "build promotion" profile and exposed through different repository groups to allow for additional testing and qualification before a final release. <xref linkend="fig-staging-multi-scenario" /> illustrates a potential use for multi-level staging:

  • Stage: A developer publishes artifacts to a QA staging profile which exposes the staged artifacts in a QA repository group used by an internal quality assurance team for testing.

  • Promote to Beta: Once the QA team has successfully completed testing, they promote the temporary staging repository to build promotion profile which will expose the staged artifacts to a limited set of customers who have agreed to act as a beta testers for a new feature.

  • Release: Once this closed beta testing period is finished, the staged repository is then released and the artifacts it contains are published to a hosted release repository and exposed via the public repository group.

Multi-level Staging and Build Promotion

figs/web/multi-level-staging.png

To support this multi-level staging feature, you can configure Build Promotion profiles as detailed in <xref linkend="staging-sect-config-build-profile" />. Once you have promoted a Staging Repository to a Build Promotion profile, you can drop, promote, or release the artifacts it contains as detailed in <xref linkend="sect-staging-using-build" />.

Using the Nexus Staging Suite

To use the Staging Suite in Nexus Professional, start Nexus and look for the Staging Profiles, Staging Repositories, Staging Rulesets, and Staging Upload options in the left-hand navigation menu of the Nexus interface. If you see the links shown in <xref linkend="fig-staging-links" />, the Staging Suite is available and ready to be configured.

Configuring Staging Profiles

Staging Profiles define the rules by which artifact deployments are staged in Staging Repositories. Staging Repositories are created as they are needed and are the primary mechanism by which Nexus users can promote or discard the contents of a staging repository to a hosted repository. A staging profile uses a Repository Target to match artifacts as they are deployed. If a matching artifact is deployed to Nexus, the Staging Suite will intercept this deployment and store the artifact in a staging repository.

The process for configuring a new Staging Profile is as follows:

  1. Configure a Repository Target to match artifacts under the groupId you will be deploying artifacts to. If you are releasing all of your software under the groupId com.example, you would configure a target that matches the pattern "./com/example/.".

  2. Create a new Staging Profile using the target defined in the previous step. When you configure this staging profile, you will be defining a target repository group. When the Staging Suite intercepts an artifact and places it in a staging repository, this staging repository will be added to the specified target repository group.

  3. Assign the appropriate Staging-specific roles to the appropriate users. When you create a Staging Profile, Nexus also creates two new roles that grant access and privileges to the repositories created by this Staging Profile.

The following sections provide a more detailed look at the process of configuring a single staging profile in Nexus Professional.

Configuring a Repository Target

The Staging Suite intercepts deployments to repository targets. For example, if you wanted to intercept all deployments to the com.sonatype.sample groupId, you would create a Repository Target called the "Sample Target" with a pattern expression of "<varname>./com/sonatype/sample/.". Do this by clicking on "Repository Targets" in the left-hand navigation menu in Nexus and then clicking on the <guibutton>Add

Adding a Repository Target for com.sonatype.sample

figs/web/staging_make-target.png

Configuring Staging Profiles

Staging profiles control the process by which artifacts are selected for staging. When you define a Staging profile, you are defining a set of rules which will control the way in which Nexus intercepts an artifact deployment. When you click on Staging Profiles in the Nexus menu, you will see a list of configured staging profiles. Clicking on Add… will display the dropdown menu shown in <xref linkend="fig-staging-add-staging-profile" />.

Multi-level Staging and Build Promotion

figs/web/staging_add-staging-profile.png

Selecting Staging Profile will create a new Staging Profile and display the form shown in <xref linkend="fig-staging-edit-profile" />.

<xref linkend="fig-staging-edit-profile" /> defines a Staging Profile using the Repository Target configured in <xref linkend="staging-sect-define-target" />. This target will match all artifacts under the <varname>com.sonatype.sample groupId (or the <filename>com/sonatype/sample repository path). This staging profile uses the "Maven2 (hosted, release)" as a template for newly created temporary staging repositories, and it will automatically add closed staging repositories to the Public Repositories group.

Editing a Staging Profile

figs/web/staging_profile-edit.png

This form allows you to configure a profile. Every profile has a name, is associated with a Repository Target, and points to a template to use when creating a new staging repository. The Staging Profile configuration panel contains the following fields:

Profile Name

The Name of the Staging Profile. This can be an arbitrary value. It is simply a convenience for the Nexus Administrator, and it is also used to create Nexus roles that are used to grant permissions to view and manipulate staging repositories created by this profile.

Staging Mode

This field contains the options "Deploy", "UI Upload", and "Deploy and UI Upload". This controls how artifacts can be staged to this staging profile. If Deploy is selected, artifacts can only be deployed using Maven to upload build artifacts. If UI Upload is selected, users can upload artifacts to Nexus using the Nexus user interface.

Template

Defines a template for the temporary staging repository. The current version of Nexus Professional provides with the options "Maven2 (hosted, release)" and "Maven1 (hosted, release)".

Repository Target

This is a reference to the target which we defined in <xref linkend="staging-sect-define-target" />. When a developer deploys an artifact to the Staging URL, the Staging Suite will check to see if the artifact matches the patterns defined in the Repository Target. The Target defines the "trigger" for the creation of a Staging Repository.

Release Repository

Staged artifacts are stored in a temporary staging repository which is made available via Target Groups. Once a staged deployment has been successfully tested, artifacts contained in the temporary staging repository are promoted to a hosted repository. The Release Repository setting configures the target release repository for this staging profile.

Content Type

Nexus can create staging repositories for repositories of type maven1, maven2, and Eclipse P2 repositories. This value is automatically selected based on the chosen template. This chapter only deals with maven2 repository types.

Target Groups

When a Staging Repository is "closed" and is made available to users and developers involved in the testing process, the temporary Staging Repository is added to one or more Repository Groups. This field defines those groups.

Close Repository Notification Settings

After a developer has deployed a set of related release artifacts, a staging repository is "closed". This means that no further artifacts can be deployed to the same staging repository. A repository would be closed when a developer is satisfied that a collection of staged artifacts is ready to be certified by a manager or a quality assurance resource. In this setting, it is possible to define email addresses and Roles which should be notified of a staging repository being closed. A notification email will be sent to all specified email addresses, as well as all Nexus users in the specified roles, informing that a staging repository has been closed. It is also possible to select that the creator of the staging repository receives this notification.

Promotion Repository Notification Settings

Once a closed staging repository has been certified by whoever is responsible for testing and checking a staged release, it can then be promoted (published) or dropped (discarded). In this setting, it is possible define email addresses and Roles which should be notified of a staging repository being promoted. A notification email will be sent to all specified email addresses, as well as all Nexus users in the specified roles, informing that a staging repository has been promoted. It is also possible to select that the creator of the staging repository receives this notification.

Drop Repository Notification Settings

In this setting, it is possible define email addresses and Roles which should be notified of a staging repository being dropped. A notification email will be sent to all specified email addresses, as well as all Nexus users in the specified roles, informing that a staging repository has been dropped. It is also possible to select that the creator of the staging repository receives this notification.

Close Repository Staging Rulesets

This defines the rulesets which will be applied to a staging repository before it can be closed. If the staging repository does not pass the rules defined in the specified rulesets, you will be unable to close it. For more information about rulesets, see <xref linkend="staging-sect-rulesets" />.

Promote Repository Staging Rulesets

This defines the rulesets which will be applied to a staging repository on promotion. If the staging repository does not pass the rules defined in the specified rulesets, the promotion will fail with an error message supplied by the failing rule. For more information about rulesets, see <xref linkend="staging-sect-rulesets" />.

Once you’ve created a Staging Repository with the values shown in <xref linkend="fig-staging-edit-profile" />, you are ready to perform a test deployment to the Staging URL.

Configuring Build Promotion Profiles

A Build Promotion profile is used when you need to add an additional step between initial staging and final release. To add a new Build Promotion profile, open the Staging Profiles link from the Nexus menu and click on Add… to display the dropdown menu shown in <xref linkend="fig-staging-build-promo-link" />. Select Build Promotion Profile from this dropdown to create a new Build Promotion Profile.

After creating a new Build Promotion profile, you will see the form shown in <xref linkend="fig-staging-build-promo-profile" />. This form contains the following configuration fields:

Profile Name

This is the name for the Build Promotion profile which will be displayed in the promotion dialog shown in <xref linkend="fig-staging-promote-stating" />. This name will also be associated with repositories created from this promotion profile.

Template

This is the template for repositories generated by this Build Promotion profile. The default value for this field is "Maven2 (group)".

Target Groups

This is the most important configuration field for a Build Promotion profile. It controls the group that promoted artifacts will be made available through. Artifacts can be made available through one or more groups.

Configuring a Build Promotion Profile

figs/web/staging_closed-beta-promotion-group.png

Adding the Staging Deployer Role

To perform a staged deployment, the user deploying the artifact must have the "Staging: Deployer (admin)" role or the "Staging: Deployer" role for a specific Staging Profile.

When you create a Staging Profile, Nexus will create two new Nexus roles that grant permissions specific to that staging profile. If you created the Staging profile from the previous section, Nexus would have created two roles:

"Staging: Repositories (Release Staging Profile)"

This role grants a user read and view access to the staging repositories created by a specific staging profile.

"Staging: Deployer (Release Staging Profile)"

This role grants all of the privileges from the Staging: Repositories role and it grants the user permission to deploy artifacts, close a staging repository, and promote or drop a staging repository created by a specific staging profile.

In addition to the profile-specific staging roles, the Staging Suite also defines two universal roles which grant read-only or deployer rights across all staging repositories. These roles are:

"Staging: Repositories (admin)"

This role grants a user read and view access to all staging repositories.

"Staging: Deployer (admin)

This role grants a user all of the privileges from the Staging: Repositories role and it grants the user permission to deploy artifacts to any staging repository, close all staging repositories, and promote or drop all staging repositories.

To configure the deployment user with the appropriate staging role, click on Users under the Security menu in the Nexus menu. Once you see the Users panel, click on the deployment user to edit this user’s roles. If the Staging Suite is installed, you should see the "Staging: Deployer (admin)" role listed in Available Roles. Select the "Staging: Deployer (admin)" role and then click the left arrow to add this role to the deployment user’s list of assigned roles.

Assigning the Staging Deployer Role to the deployment user

figs/web/staging_deployer-role.png

Once the deployment user has the "Staging: Deployer (admin)" role, you can then use this user to deploy to the staging URL and trigger any Staging Profile. Without this permission, the deployment user would not be able to publish a staged artifact. If you need to add a specific permission to activate a single Staging Profile, you would select that specific role in the Available Roles list shown in <xref linkend="fig-staging-assigning-role" />. In this figure, note that there are two "Staging: Deployer" roles: one for general administrative permission to deploy to any staging profile, and another which targets a specific staging profile.

Performing a Staged Deployment with Maven

In the previous section, you created a Staging Profile which references the Repository Target created in <xref linkend="staging-sect-define-target" />. If the Staging Suite is configured correctly, any deployment to the staging URL under the groupId com.sonatype.sample should be intercepted by the Staging Suite and placed in a temporary staging repository. Once this repository has been closed, it will be made available in the Target Group you selected when you configured the Staging Profile in <xref linkend="staging-sect-config-profile" />.

In this section, you will create a new project using the Maven Archetype plugin to test the Staging Profile you created in the previous section.

Creating a New Project

To create a new project run <command>mvn archetype:generate. Running this at the command line will bring up a list of archetypes, choose the default maven-archetype-quickstart or number 16, and use the identifier values listed in <xref linkend="tbl-staging-new-project" /> for the new project.

Table 11. Identifiers for New Project

Identifier

Value

groupId

com.sonatype.sample

artifactId

staging-test

version

1.0

package

com.sonatype.sample

If the archetype generate goal is executed successfully, you should have output which resembles the following screen listing:

$ <command>mvn archetype:generate
...
[INFO] [archetype:generate]
[INFO] Generating project in Interactive mode
[INFO] No archetype defined. Using maven-archetype-quickstart \
(org.apache.maven.archetypes:maven-archetype-quickstart:1.0)
Choose archetype:
1: internal -> appfuse-basic-jsf (AppFuse archetype for creating a \
web application with Hibernate, Spring and JSF)
...
41: internal -> gmaven-archetype-mojo (Groovy mojo archetype)
Choose a number:  (1/.../41) 16: : <command>16
Define value for groupId: : <command>com.sonatype.sample
Define value for artifactId: : <command>staging-test
Define value for version:  1.0-SNAPSHOT: : <command>1.0
Define value for package:  com.sonatype.sample: : <command>com.sonatype.sample
Confirm properties configuration:
groupId: com.sonatype.sample
artifactId: staging-test
version: 1.0
package: com.sonatype.sample
Y: :
[INFO] Parameter: groupId, Value: com.sonatype.sample
[INFO] Parameter: packageName, Value: com.sonatype.sample
[INFO] Parameter: basedir, Value: /private/tmp
[INFO] Parameter: package, Value: com.sonatype.sample
[INFO] Parameter: version, Value: 1.0
[INFO] Parameter: artifactId, Value: staging-test
...
[INFO] BUILD SUCCESSFUL

Update the POM: Deployment Configuration

To deploy a staged released, a developer needs to deploy to the staging URL. To configure this new project to deploy to the Staging URL, add the a <sgmltag>distributionManagement element to the stage-test project’s POM.

Listing the Staging URL in distributionManagement
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
http://maven.apache.org/maven-v4_0_0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.sonatype.sample</groupId>
  <artifactId>staging-test</artifactId>
  <packaging>jar</packaging>
  <version>1.0</version>
  <name>staging-test</name>
  <url>http://maven.apache.org</url>
  <dependencies>
    <dependency>
      <groupId>junit</groupId>
      <artifactId>junit</artifactId>
      <version>3.8.1</version>
      <scope>test</scope>
    </dependency>
  </dependencies>
  <distributionManagement>
    <repository>
      <id>nexus</id>
      <name>Nexus Staging Repo</name>
      <url>http://localhost:8081/nexus/service/local/staging/deploy/maven2/</url>
    </repository>
  </distributionManagement>
</project>

This configuration element, distributionManagement, defines the repository to which our deployment will be made. It references the Staging Suite’s Staging URL: http://localhost:8081/nexus/service/local/staging/deploy/maven2

This URL acts as a something of a virtual repository to be published to. If an artifact being published matches one of the Repository Targets in a Staging Profile, that Staging Profile is "activated" and a temporary Staging Repository is created for a specific client as defined by the combination of a client’s IP address, Deployment User name, and User-Agent.

Update settings.xml with Deployment Credentials

To successfully deploy to your Nexus instance, you will need to update your Maven Settings with the credentials for the deployment user. These credentials are stored in the Maven Settings file in /.m2/settings.xml. To add these credentials, add the following element to the servers element in your /.m2/settings.xml file as shown in <xref linkend="ex-staging-deployment-credentials" />.

Listing deployment credentials in Maven Settings
<settings>
  ...
  <servers>
    ...
    <server>
      <id>nexus</id>
      <username>deployment</username>
      <password>deployment123</password>
    </server>
  </servers>
  ...
</settings>

Note that the server identifier listed in <xref linkend="ex-staging-deployment-credentials" /> matches the server identifier listed in <xref linkend="ex-staging-dist-management" />. The deployment credential listed in <xref linkend="ex-staging-deployment-credentials" /> contains the default password for the Nexus deployment user - deployment123. You should change this password to match the deployment password for your Nexus installation.

Deploying to a Staged Repository

Once the sample project’s <sgmltag>distributionManagement has been set to point at the Nexus Staging URL and your deployment credentials are updated in your ~/.m2/settings.xml file, you can deploy to the Staging URL. To do this, run <command>mvn deploy

$ mvn deploy
[INFO] Scanning for projects...
[INFO] ------------------------------------------------------------------------
[INFO] Building staging-test
[INFO]    task-segment: [deploy]
[INFO] ------------------------------------------------------------------------
[INFO] [resources:resources]
[INFO] Using default encoding to copy filtered resources.
[INFO] [compiler:compile]
[INFO] Nothing to compile - all classes are up to date
[INFO] [resources:testResources]
[INFO] Using default encoding to copy filtered resources.
[INFO] [compiler:testCompile]
[INFO] Nothing to compile - all classes are up to date
[INFO] [surefire:test]
[INFO] Surefire report directory: /private/tmp/staging-test/target/surefire-reports

...
[INFO] [jar:jar]
[INFO] [install:install]
[INFO] Installing /private/tmp/staging-test/target/staging-test-1.0.jar to \
~/.m2/repository/com/sonatype/sample/staging-test/1.0/staging-test-1.0.jar
[INFO] [deploy:deploy]
altDeploymentRepository = null
Uploading: http://localhost:8081/nexus/service/local/staging/deploy/maven2/\
com/sonatype/sample/staging-test/1.0/staging-test-1.0.jar
2K uploaded
[INFO] Uploading project information for staging-test 1.0
[INFO] Retrieving previous metadata from nexus
[INFO] repository metadata for: 'artifact com.sonatype.sample:staging-test'
could not be found on repository: nexus, so will be created
[INFO] Uploading repository metadata for: 'artifact com.sonatype.sample:staging-test'
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL

Uploading a Staged Deployment in Nexus

You can also upload a staged deployment via the Nexus interface. To upload a staged deployment, select Staging Upload from the Nexus menu. Clicking Staging Upload will show the panel shown in <xref linkend="fig-staging-artifact-upload" />.

Uploading a Staged Deployment in Nexus

figs/web/staging_artifact-upload.png

To upload an artifact, click on Select Artifact(s) for Upload… and select one or more artifacts from the filesystem to upload. Once you have selected an artifact, you can modify the classifier and the extension before clicking on the Add Artifact button. Once you have clicked on the Add Artifact button, you can then configure the source of the Group, Artifact, Version (GAV) parameters.

If the artifact you are uploading is a JAR file that was created by Maven it will already have POM information embedded in it, but if you are uploading a JAR from a vendor you will likely need to set the Group Identifier, Artifact Identifier, and Version manually. To do this, select GAV Parameters from the GAV Definition dropdown at the top of this form. Selecting GAV Parameters will expose a set of form fields which will let you set the Group, Artifact, Version, and Packaging of the artifacts being uploaded. If you would prefer to set the Group, Artifact, and Version from a POM file which was associated with the uploaded artifact, select From POM in the GAV Definition dropdown. Selecting From POM in this dropdown will expose a button labeled "Select POM to Upload". Once a POM file has been selected for upload, the name of the POM file will be displayed in the form field below this button.

The Staging Upload panel supports multiple artifacts with the same Group, Artifact, and Version identifiers. For example, if you need to upload multiple artifacts with different classifiers, you may do so by clicking on Select Artifact(s) for Upload and Add Artifact multiple times. This interface also accepts an Artifact Bundle which is a JAR that contains more than one artifact.

Once a staging artifact upload has been completely configured, click on Upload Artifact(s) button to begin the upload process. Nexus will upload the artifacts to the Staging URL which will trigger any staging profiles that are activated by the upload. If a staging profile is activated, a new staging repository will be created and can be managed using the procedures outlined in <xref linkend="staging-sect-managing-staging" />.

Managing Rulesets

Nexus Professional has the ability to define staging rules that must be satisfied before a staging repository can be promoted.

Managing Staging Rulesets

Staging Rulesets are groups of rules that are applied to a Staging repository at promotion time. A staging repository associated with a staging ruleset cannot be promoted until all of the rules associated with the rulesets have been satisfied. This feature allows you to set standards for your own hosted repositories, and it is the mechanism that is used to guarantee the consistency of artifacts stored in the Maven Central repository.

Nexus Professional contains the following rules:

Staging Javadoc Validation

The Staging Javadoc Validation rule will verify that every project has an artifact with the javadoc classifier. If you attempt to promote a staging repository which contains artifacts not accompanied by "-javadoc.jar" artifacts, this validation rule will fail.

Staging Artifact Uniqueness Validation

This rule checks to see that the artifact being released, promoted, or staged is unique in a particular Nexus instance.

Staging Checksum Validation

This rule validates file checksums against published artifacts.

Staging No Release Repository

This rule will fail if a particular staging profile is not defined with a release repository.

Staging POM Validation

The Staging POM Validation rule will verify the following properties of all POMs to be promoted:

  • Project URL - project/url

  • Project Licenses - project/licenses

  • Project SCM Information - project/scm

If any of these POM elements are missing or empty, this Staging Ruleset will cause a promotion to fail.

Staging Signature Validation

The Staging Signature Validation rule verifies that every item in the repository has a valid PGP signature. If you attempt to promote a staging repository which contains artifacts not accompanied by valid PGP signature, this validation will fail.

Staging Sources Validation

The Staging Sources Validation rule will verify that every project has an artifact with the sources classifier. If you attempt to promote a staging repository which contains artifacts not accompanied by "-sources.jar" artifacts, this validation rule will fail.

To create a Staging Ruleset, click on the Staging Ruleset link in the Nexus Menu. This will load the interface shown in <xref linkend="fig-staging-rulesets" />. The Staging Ruleset panel is used to define sets of rules that can be applied to Staging Profiles. <xref linkend="fig-staging-rulesets" /> shows a ruleset which contains all four predefined staging rules.

Creating a Staging Ruleset

figs/web/staging-rulesets.png

Defining Rulesets for Promotion

To define a ruleset to be used for promotion, click on Staging in the Nexus menu and select a Staging Profile. Click on the Configuration tab, and scroll down to the Promote Repository Staging Rulesets section of the Staging Profile configuration as shown in <xref linkend="fig-staging-associate-ruleset" />. The next time you attempt to promote a staging repository that was created with this profile, Nexus Professional will check that all of the rules in the associated rulesets are being adhered to.

Associating a Staging Ruleset with a Staging Profile

figs/web/staging-rulesets-associate.png

Managing Staging Repositories in Nexus

Once you complete the process outlined in <xref linkend="staging-sect-deployment" />, you will then have an automatically generated Staging Repository. In this section, you will walk through the process of managing staging repositories. Once a staging repository has been created, there are two steps in the lifecycle of a staging repository. Once you have deployed a set of related artifacts, you must "Close" the repository moving it from an "Open" to a "Closed" state. Once a repository is in the "Closed" state it is added to a Repository Group and is made available for testing purposes. Once testing is completed, a Nexus administrator can either Promote or Drop a Closed repository. If the repository is Dropped, the repository is discarded and removed from the Repository Group. If the repository is Promoted, the Nexus administrator can select a Hosted repository and publish the contents of the temporary staging repository to a Hosted repository.

Closing an Open Repository

Once you deploy an artifact that triggers a staging profile, Nexus Staging Suite will create a repository that contains the artifacts you deployed. A separate staging repository is created for every combination of User ID, IP Address, and User Agent. This means that you can perform more than one deployment to a single Staging Repository as long as you perform the deployment from the same IP, with the same deployment user, and the same installation of Maven. You can perform multiple deployments to an "Open" staging repository, to see a list of these temporary "Open" Staging repositories, select "Staging" from the Nexus menu and click on the appropriate Staging Profile to browse a list of staging repositories which correspond to a staging profile.

Listing Repositories Associated with a Staging Profile

figs/web/staging_close-repository.png

Once you are ready to start testing the staging repository, you will need to transition the staging repository from the "Open" state to the "Closed" state. This will close the temporary staging repository to more deployments. To close a repository, right-click on the repository in the Staging Repositories panel and select "Close". This will bring up the following dialog for a staging deployer to describe the contents of a staging repository. This description field can be used to pass essential information to the person that needs to test a deployment. In <xref linkend="fig-staging-close-description" />, the description field is used to describe the release for the user that needs to certify and promote a release.

Confirmation and Description Dialog for Closing a Staging Repository

figs/web/staging_close-confirm.png

Confirming this state transition will close the repository and add the repository to a repository group. Once a repository has been closed, it will be listed as "Closed" in the Profile’s Repositories tab.

Closed Repository After Selecting Finish

figs/web/staging_closed-repository.png

Using the Staging Repository

Once the Staging Repository has been closed, it will automatically be added to the Repository Group that was specified in the Staging Profile. <xref linkend="fig-staging-add-to-group" /> shows an instance of a staging repository appended to the end of a group named "Public Repositories". This has the effect of making the staged artifacts available to everyone who is referencing this public group. Developers who are referencing this public repository group can now test and interact with the staged artifacts as if they were published to a Hosted repository. While the artifacts are made available in a repository group, the fact that they are held in a temporary staging directory gives the administrator the option of promoting this set of artifacts to a Hosted repository or dropping this temporary staging repository if there are problems discovered during the testing and certification process for a release.

Staging Repository Added to the End of a Repository Group

figs/web/staging_staged-to-group.png

Once a staging repository is closed, you can also browse and search the repository. To view Staging Repositories, click on Browse Repositories and then select Nexus Managed Repositories as shown in <xref linkend="fig-staging-selecting-nexus" />.

Viewing Nexus Managed Repositories

figs/web/staging_select-nexus-managed.png

Once you’ve selected Nexus Managed Repositories, Nexus will then show you all of the repositories that have been created by the Nexus Staging Suite. You can select and browse this temporary Staging Repository as you would any other repository.

Browsing a Staging Repository

figs/web/staging_browsing-staged.png

You can browse the contents of a staging repository from the Staging Repositories panel. Click on Staging Repositories in the Nexus menu, click on a Staging Repository to browse the contents and perform operations a staging repository.

Browsing Repository via Staging Profiles

figs/web/staging_browsing-via-profiles.png

Releasing a Staging Repository

Once you are finished testing or certifying that the contents of a Staging Repository are correct, you are ready to either Release or Drop the Staging Repository. Dropping the Staging Repository will delete the temporary staging repository from Nexus and remove any reference to this repository from the groups it was associated with. Releasing the Staging Repository allows you to publish the contents of this temporary repository to a Hosted repository.

To release a Staging Repository select Staging from the Nexus menu and then click on the appropriate Staging Profile. This will display a list of Staging Repositories associated with that Staging Profile. To release the contents of a repository, load the list of Staging Repositories, check the box next to the staging repository you which to promote and then click the Release button shown in <xref linkend="fig-staging-promote" />.

Promoting a Staging Repository

figs/web/staging_promote-repository.png

Once you click Release, the Nexus Staging Suite will ask you to supply a description for this release action.

Selecting the Destination Repository for Staged Repository Promotion

figs/web/staging_promote-confirm.png

Supplying a description and clicking on Release will publish the contents of a Staging Repository to a Hosted repository and delete the Staging Repository from Nexus.

Confirmation Dialog for Repository Promotion

figs/web/staging_success-promote.png

Promoting a Staging Repository

If you have a staging repository that you want to promote to a Build Promotion profile, open the list of Staging Repositories by selecting Staging Repositories from the Nexus menu, select the repository you intend to promote, and click the Promote button as shown in <xref linkend="fig-staging-promote-button" />.

Promoting a Staging Repository

figs/web/staging_promote-to-group-button.png

After clicking the Promote button the Promote Staging Repository shown in <xref linkend="fig-staging-promote-stating" /> will be displayed. In this dialog, you can choose the Build Promotion profile to promote the staging repository to, and you can supply a short description of the promotion. Clicking on the Promote button in this dialog will promote the staging profile to a build promotion profile and expose the contents of the selected staging repository through a group associated with the build promotion profile.

Multi-level Staging and Build Promotion

figs/web/staging_promote-to-group.png

After you promote a staging repository to a Build Promotion profile the build promotion profile will create a temporary repository which contains the contents of the promoted staging repository. The staging repository will be a Group Member of the Build Promotion repository. One or more staging repositories can be promoted to a single Build Promotion profile, and you can browse the Group Member by selecting the Build Promotion repository and viewing the Group Member tab as shown in <xref linkend="fig-staging-group-members" />.

Multi-level Staging and Build Promotion

figs/web/staging_browse-group-members.png

Releasing, Promoting, and Dropping Build Promotion Profiles

When you configure a Build Promotion profile and promote Staging Repositories to promotion profiles, each Build Promotion profile creates a repository which contains one or more Staging Repositories. Just like you can promote the contents of a Staging Repository to a Build Promotion profile, you can also promote the contents of a Build Promotion profile to another Build Promotion profile. When you do this you can create hierarchies of staging repositories and build promotion profiles which can then be dropped or released together.

Releasing, Promoting, and Dropping Build Promotion Profiles

figs/web/staging-promotion.png

When you promote a staging repository to a build promotion profile, you make the contents of a staging repository available via a repository group associated with a build promotion profile. For example, if you staged a few artifacts to a QA Staging Repository and then subsequently promoted that repository to a Closed Beta Build Promotion group, the contents of the QA Staging Repository would initially be made available via a QA Repository Group. After a build promotion, these artifacts would also be available via a Closed Beta repository group. You can take it one step further and promote the contents of the Closed Beta Build Promotion profile to yet another Build Promotion profile. In this way you can have an arbitrary number of intermediate steps between the initial staging deployment and the final release.

If you drop the contents of a build promotion profile, you roll back to the previous state. For example, if you decided to drop the contents of the Closed Beta build promotion group, Nexus will revert the status of the Staging Repository from promoted to closed, and make the artifacts available via the QA Staging Repository. The effects of promoting, dropping, and releasing artifacts through a series of Staging Profiles and Build Promotion Profiles is shown in <xref linkend="fig-staging-build-promo-agg" />.

When you perform a release on a Build Promotion profile, each Staging Repository is going to release artifacts to the Release Repository configured in <xref linkend="fig-staging-edit-profile" />. Because a Build Repository can contain one or more promoted staging repositories, this means that releasing a Build Promotion profile can cause artifacts to be published to more than one Release Repository. Build Promotion profiles are not directly related to release repositories, only staging profiles are directly associated with target release repositories. <xref linkend="fig-staging-multi-to-one" /> illustrates this behavior with two independent Staging Repositories each configured with a separate Release Repository. Releasing the Build Promotion profile causes Nexus to publish each Staging Repository to a separate hosted repository.

Promoting Multiple Repositories to the Same Build Promotion Profile

figs/web/multiple-promotion-release.png

Managing Staging Repositories with the Nexus Maven Plugin

You can do everything that was described in <xref linkend="staging-sect-managing-staging" /> with the Nexus Maven Plugin. Using the Nexus Maven Plugin you can:

  • Close a Staging Repository

  • Promote a Staging Repository

  • Drop a Staging Repository

  • List All Available Staging Repositories

Running the Nexus Maven Plugin

To invoke goals in the Nexus Maven plugin, you will want to add the appropriate plugin group to your Maven settings file. Add the org.sonatype.plugins groupId to <filename>~/.m2/settings.xml as shown in <xref linkend="ex-staging-nexus-plugin-group" />.

Adding org.sonatype.plugins to pluginGroups in Maven Settings
<settings>
  ...
  <pluginGroups>
    <pluginGroup>org.sonatype.plugins</pluginGroup>
  </pluginGroups>
  ...
</settings>

Adding the <varname>org.sonatype.plugins group to your Maven Settings will allow you to run the following goals from the Nexus Maven Plugin:

nexus:staging-close

This goal will close a staging repository from Maven. This goal in the Nexus Maven plugin corresponds to the procedure described in <xref linkend="staging-sect-closing" />.

nexus:staging-list

This goal will list all of the staging repositories which are currently visible to a user.

nexus:staging-drop

This goal allows you to drop a specific staging repository. If no repositories are specified for this goal, this plugin will present an interactive menu listing all of the closed staging repositories currently eligible for a drop operation.

nexus:staging-promote

This goal allows you to promote a specific repository. If no repositories are specified for this goal, this plugin will present an interactive menu listing all of the closed staging repositories currently eligible for a promote operation.

Once you have configured the <sgmltag>pluginGroup in your Maven Settings file, you can run the Nexus Maven plugin from the command line. In order to access the staging suite in your Nexus instance, the plugin must be told where Nexus is.

$ mvn nexus:staging-list

Configuring Nexus Maven Plugin for Staging

All of the Staging goals in the Nexus Maven plugin require security credentials and a base URL for the Nexus server you are attempting to manage. You can specify security credentials by supplying a username and password or by supplying a server id that corresponds to a server in your Maven Settings (~/.m2/settings.xml). The common configuration parameters and security configuration properties are:

nexusUrl

Points to the Nexus server installation’s base URL. If you have installed Nexus on your local machine, this would be http://localhost:8081/nexus/

username

Username to use for authenticating to Nexus. Default value is \${user.name}.

password

Password to use for authenticating to Nexus

serverAuthId

You should specify either username and password or the serverAuthId. If you specify a value for serverAuthId, the Nexus Maven plugin is going to look at the contents of your <filename>~/.m2/settings.xml file and use the username and password from a server definition.

In most cases a valid user login will be required to access your staging information. By default, if you don’t specify the nexusUrl and password parameters, the plugin will prompt you for them. If you don’t specify the username parameter, the Java System property <varname>\${user.name}

In addition to these security options, all of the staging goals have a common configuration property which controls the logging level.

verboseDebug

If verboseDebug is set to true Maven will print out debug messages that detail the plugin’s interaction with Nexus.

Listing Your Open Staging Repositories

Once you’ve deployed one or more sets of artifacts as release candidate to Nexus, you’ll have one or more open staging repositories. There are a variety of actions you can take with these repositories, but maybe one of the most basic is to list them. This gives you a pretty good view into the status of your release(s). The basic command is:

$ <command>mvn nexus:staging-list
[...]
[INFO] Logging into Nexus: http://localhost:8082/nexus
[INFO] User: testuser
[INFO]


[INFO] The following OPEN staging repositories were found:

-  staging-003 (profile: Example Profile)
URL: http://localhost:8082/nexus/content/repositories/staging-003


[INFO] The following CLOSED staging repositories were found:

-  staging-001 (profile: Example Profile)
URL: http://localhost:8082/nexus/content/repositories/staging-001
Description: This is a test repository

-  staging-002 (profile: Example Profile)
URL: http://localhost:8082/nexus/content/repositories/staging-002
Description: This is another test repository

You can find more information about this Mojo <ulink
url="http://plugins.sonatype.org/nexus-maven-plugin/usage-staging.html">here

Closing a Staging Repository

Before your team can run any tests against the set of artifacts that constitute your release, you need to mark the open staging repository as closed. This means that no additional artifacts can be added to that specific staging repository, making the set of artifacts it contains an immutable snapshot. When it is closed, the repository will become available for artifact resolution. The basic command is:

$ mvn nexus:staging-close
[INFO]


Available Staging Repositories:


1: staging-002 (profile: Example Profile)
URL: http://localhost:8082/nexus/content/repositories/staging-002



Select a repository to close (1) 1: : 1

Repository Description: This is a test repository
[INFO] Finishing staging repository for: 'com.myco:my-project:1':

-  staging-002 (profile: Example Profile)
URL: http://localhost:8082/nexus/content/repositories/staging-002


[INFO] The following CLOSED staging repositories were found for: \
'com.myco:my-project:1':

-  staging-001 (profile: Example Profile)
URL: http://localhost:8082/nexus/content/repositories/staging-001
Description: This is a test repository

-  staging-002 (profile: Example Profile)
URL: http://localhost:8082/nexus/content/repositories/staging-002
Description: This is another test repository

The output above shows that the staging-close Mojo found an open staging repository - staging-001 - for the current project, then told Nexus to close it. Afterward, it displayed the list of closed staging repositories, which included the one we just closed. If you don’t have an open staging repository, you’ll see something like this instead:

No open staging repositories found. Nothing to do!


[INFO] The following CLOSED staging repositories were found for: \
'com.myco:my-project:1':

-  staging-001 (profile: Example Profile)
URL: http://localhost:8082/nexus/content/repositories/staging-001
Description: This is a test repository

-  staging-002 (profile: Example Profile)
URL: http://localhost:8082/nexus/content/repositories/staging-002
Description: This is another test repository

You can find more information about this Mojo <ulink
url="http://plugins.sonatype.org/nexus-maven-plugin/staging-close-mojo.html">here

Dropping a Closed Staging Repository

In the unfortunate event that your project artifacts fail during testing, you may need to drop the staging repository that houses them, in order to avoid confusing them with newer candidate releases. The basic command is:

$ mvn nexus:staging-drop
[INFO]

Available Staging Repositories:

1: staging-006 (profile: Example Profile)
URL: http://localhost:8082/nexus/content/repositories/staging-006
Description: This is a test repository

Select a repository to drop (1) 1: : 1
[INFO] Dropping staged repository:

-  staging-006 (profile: Example Profile)
URL: http://localhost:8082/nexus/content/repositories/staging-006
Description: This is a test repository

The Mojo will present you with a list of closed staging repositories, with the first in the list selected as the default response. If you simply hit the Enter key, the default will be used; otherwise, the repository corresponding to the number you select will be used. If you have no closed staging repositories, you’ll see something like this instead:

[INFO]

No closed staging repositories found. Nothing to do!

You can find more information about this Mojo <ulink
url="http://plugins.sonatype.org/nexus-maven-plugin/staging-drop-mojo.html">here

Promoting a Closed Staging Repository

On the other hand, if your project artifacts pass all tests, you will find that you need to promote the staging repository that houses them, in order to finalize the release and make the artifacts available for public consumption. The basic command is:

$ mvn nexus:staging-promote
[INFO]

Available Staging Repositories:

1: staging-006 (profile: Example Profile)
URL: http://localhost:8082/nexus/content/repositories/staging-006
Description: This is a test repository

Select a repository to promote (1) 1: : 1
Target Repository ID: releases
[INFO] Promoting staging repository to: releases:

-  staging-006 (profile: Example Profile)
URL: http://localhost:8082/nexus/content/repositories/staging-006
Description: This is a test repository

The Mojo will present you with a list of closed staging repositories, with the first in the list selected as the default response. If you simply hit the Enter key, the default will be used; otherwise, the repository corresponding to the number you select will be used. If you have no closed staging repositories, you’ll see something like this instead:

[INFO]

No closed staging repositories found. Nothing to do!

You can find more information about this Mojo <ulink
url="http://plugins.sonatype.org/nexus-maven-plugin/staging-promote-mojo.html">here